@buba_71/levit 0.3.4 → 0.4.0

package/README.md

@@ -34,7 +34,8 @@ Its role is simple:
 ## What levit-kit does
 
 - Initializes a standardized project structure
-- Installs explicit conventions
+- Installs explicit conventions for **AI-Driven Development (AIDD)**
+- Provides a protocol for Human-AI collaboration (Intents, Decisions, Evals)
 - Facilitates human and agent onboarding
 - Reduces unnecessary variability between projects
 
@@ -78,6 +79,18 @@ Levit-kit does not remain in the project after initialization and installs no de
 
 ---
 
+## The AIDD Workflow (Human + Agent)
+
+Levit-kit installs a cognitive pipeline in your project:
+
+1.  **Human Intent**: You define *what* you want in `features/INTENT.md`.
+2.  **Agent Onboarding**: Your AI reads `.levit/AGENT_ONBOARDING.md` to learn your rules.
+3.  **Collaborative Decision**: The agent proposes technical choices in `.levit/decision-record.md`.
+4.  **Verification**: You or the agent run quality tests in `evals/`.
+5.  **Review**: The agent submits its work following a strict protocol.
+
+---
+
 ## Where does the levit command come from?
 
 The `levit` command is provided through the npm ecosystem.

package/dist/bin/cli.js

@@ -5,6 +5,9 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 const init_1 = require("../src/commands/init");
+const decision_1 = require("../src/commands/decision");
+const feature_1 = require("../src/commands/feature");
+const handoff_1 = require("../src/commands/handoff");
 const version_1 = require("../src/core/version");
 const node_path_1 = __importDefault(require("node:path"));
 function showHelp() {
@@ -13,13 +16,16 @@ Usage: levit [command] [options]
 
 Commands:
   init <project-name>    Initialize a new levit project
+  feature new            Create a new feature intent file (wizard)
+  decision new           Create a new decision record (wizard)
+  handoff new            Create an agent handoff brief (wizard)
 
 Options:
   -v, --version          Show version number
   -h, --help             Show help
 `);
 }
-function main() {
+async function main() {
     const args = process.argv.slice(2);
     if (args.includes("-h") || args.includes("--help") || args.length === 0) {
         showHelp();
@@ -50,10 +56,37 @@ function main() {
             process.exit(1);
         }
     }
+    else if (args[0] === "feature") {
+        try {
+            await (0, feature_1.featureCommand)(args.slice(1), process.cwd());
+        }
+        catch (error) {
+            console.error(error instanceof Error ? `Error: ${error.message}` : "Unexpected error");
+            process.exit(1);
+        }
+    }
+    else if (args[0] === "decision") {
+        try {
+            await (0, decision_1.decisionCommand)(args.slice(1), process.cwd());
+        }
+        catch (error) {
+            console.error(error instanceof Error ? `Error: ${error.message}` : "Unexpected error");
+            process.exit(1);
+        }
+    }
+    else if (args[0] === "handoff") {
+        try {
+            await (0, handoff_1.handoffCommand)(args.slice(1), process.cwd());
+        }
+        catch (error) {
+            console.error(error instanceof Error ? `Error: ${error.message}` : "Unexpected error");
+            process.exit(1);
+        }
+    }
     else {
         console.error(`Error: Unknown command "${args[0]}"`);
         showHelp();
         process.exit(1);
     }
 }
-main();
+void main();

package/dist/src/commands/decision.js

@@ -0,0 +1,59 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.decisionCommand = decisionCommand;
+const node_path_1 = __importDefault(require("node:path"));
+const promises_1 = __importDefault(require("node:readline/promises"));
+const levit_project_1 = require("../core/levit_project");
+const cli_args_1 = require("../core/cli_args");
+const write_file_1 = require("../core/write_file");
+const ids_1 = require("../core/ids");
+function normalizeSlug(input) {
+    return input
+        .trim()
+        .toLowerCase()
+        .replace(/[^a-z0-9\s-_]/g, "")
+        .replace(/\s+/g, "-");
+}
+async function decisionCommand(argv, cwd) {
+    const { positional, flags } = (0, cli_args_1.parseArgs)(argv);
+    const sub = positional[0];
+    if (sub !== "new") {
+        throw new Error('Usage: levit decision new [--title "..."] [--id "001"]');
+    }
+    const projectRoot = (0, levit_project_1.requireLevitProjectRoot)(cwd);
+    const yes = (0, cli_args_1.getBooleanFlag)(flags, "yes");
+    const overwrite = (0, cli_args_1.getBooleanFlag)(flags, "force");
+    let title = (0, cli_args_1.getStringFlag)(flags, "title");
+    let id = (0, cli_args_1.getStringFlag)(flags, "id");
+    const featureRef = (0, cli_args_1.getStringFlag)(flags, "feature");
+    const computedId = (0, ids_1.nextSequentialId)(node_path_1.default.join(projectRoot, ".levit", "decisions"), /^ADR-(\d+)-/);
+    if (!yes) {
+        const rl = promises_1.default.createInterface({ input: process.stdin, output: process.stdout });
+        if (!title) {
+            title = (await rl.question("Decision title: ")).trim();
+        }
+        if (!id) {
+            id = (await rl.question(`Decision id [${computedId}]: `)).trim() || computedId;
+        }
+        await rl.close();
+    }
+    if (!id) {
+        id = computedId;
+    }
+    if (!title) {
+        throw new Error("Missing --title");
+    }
+    if (!id) {
+        throw new Error("Missing --id");
+    }
+    const slug = normalizeSlug(title);
+    const fileName = `ADR-${id}-${slug}.md`;
+    const decisionPath = node_path_1.default.join(projectRoot, ".levit", "decisions", fileName);
+    const featureLine = featureRef ? `- **Feature**: ${featureRef}\n` : "";
+    const content = `# ADR ${id}: ${title}\n\n- **Date**: [YYYY-MM-DD]\n- **Status**: [Draft / Proposed / Approved]\n${featureLine}\n## Context\n[fill]\n\n## Decision\n[fill]\n\n## Rationale\n[fill]\n\n## Alternatives Considered\n[fill]\n\n## Consequences\n[fill]\n`;
+    (0, write_file_1.writeTextFile)(decisionPath, content, { overwrite });
+    process.stdout.write(`Created ${node_path_1.default.relative(projectRoot, decisionPath)}\n`);
+}

package/dist/src/commands/feature.js

@@ -0,0 +1,61 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.featureCommand = featureCommand;
+const node_path_1 = __importDefault(require("node:path"));
+const promises_1 = __importDefault(require("node:readline/promises"));
+const levit_project_1 = require("../core/levit_project");
+const cli_args_1 = require("../core/cli_args");
+const write_file_1 = require("../core/write_file");
+const ids_1 = require("../core/ids");
+function normalizeSlug(input) {
+    return input
+        .trim()
+        .toLowerCase()
+        .replace(/[^a-z0-9\s-_]/g, "")
+        .replace(/\s+/g, "-");
+}
+async function featureCommand(argv, cwd) {
+    const { positional, flags } = (0, cli_args_1.parseArgs)(argv);
+    const sub = positional[0];
+    if (sub !== "new") {
+        throw new Error('Usage: levit feature new [--title "..."] [--slug "..."] [--id "001"]');
+    }
+    const projectRoot = (0, levit_project_1.requireLevitProjectRoot)(cwd);
+    const yes = (0, cli_args_1.getBooleanFlag)(flags, "yes");
+    const overwrite = (0, cli_args_1.getBooleanFlag)(flags, "force");
+    let title = (0, cli_args_1.getStringFlag)(flags, "title");
+    let slug = (0, cli_args_1.getStringFlag)(flags, "slug");
+    let id = (0, cli_args_1.getStringFlag)(flags, "id");
+    const computedId = (0, ids_1.nextSequentialId)(node_path_1.default.join(projectRoot, "features"), /^(\d+)-/);
+    if (!yes) {
+        const rl = promises_1.default.createInterface({ input: process.stdin, output: process.stdout });
+        if (!title) {
+            title = (await rl.question("Feature title: ")).trim();
+        }
+        if (!slug) {
+            const computed = normalizeSlug(title || "");
+            slug = (await rl.question(`Feature slug [${computed}]: `)).trim() || computed;
+        }
+        if (!id) {
+            id = (await rl.question(`Feature id [${computedId}]: `)).trim() || computedId;
+        }
+        await rl.close();
+    }
+    if (!id) {
+        id = computedId;
+    }
+    if (!title) {
+        throw new Error("Missing --title");
+    }
+    if (!slug) {
+        throw new Error("Missing --slug");
+    }
+    const fileName = `${id}-${slug}.md`;
+    const featurePath = node_path_1.default.join(projectRoot, "features", fileName);
+    const content = `# INTENT: ${title}\n\n## 1. Vision (The \"Why\")\n- **User Story**: [fill]\n- **Priority**: [Low / Medium / High / Critical]\n\n## 2. Success Criteria (The \"What\")\n- [ ] Criterion 1\n\n## 3. Boundaries (The \"No\")\n- Non-goal 1\n\n## 4. Technical Constraints\n- [fill]\n\n## 5. Agent Task\n- [fill]\n`;
+    (0, write_file_1.writeTextFile)(featurePath, content, { overwrite });
+    process.stdout.write(`Created ${node_path_1.default.relative(projectRoot, featurePath)}\n`);
+}

package/dist/src/commands/handoff.js

@@ -0,0 +1,49 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.handoffCommand = handoffCommand;
+const node_path_1 = __importDefault(require("node:path"));
+const promises_1 = __importDefault(require("node:readline/promises"));
+const levit_project_1 = require("../core/levit_project");
+const cli_args_1 = require("../core/cli_args");
+const write_file_1 = require("../core/write_file");
+function isoDate() {
+    return new Date().toISOString().slice(0, 10);
+}
+async function handoffCommand(argv, cwd) {
+    const { positional, flags } = (0, cli_args_1.parseArgs)(argv);
+    const sub = positional[0];
+    if (sub !== "new") {
+        throw new Error("Usage: levit handoff new --feature <features/001-...md> [--role developer|qa|security|devops]");
+    }
+    const projectRoot = (0, levit_project_1.requireLevitProjectRoot)(cwd);
+    const yes = (0, cli_args_1.getBooleanFlag)(flags, "yes");
+    const overwrite = (0, cli_args_1.getBooleanFlag)(flags, "force");
+    let feature = (0, cli_args_1.getStringFlag)(flags, "feature");
+    let role = (0, cli_args_1.getStringFlag)(flags, "role");
+    if (!yes) {
+        const rl = promises_1.default.createInterface({ input: process.stdin, output: process.stdout });
+        if (!feature) {
+            feature = (await rl.question("Feature path (e.g. features/001-...md): ")).trim();
+        }
+        if (!role) {
+            role = (await rl.question("Role [developer]: ")).trim() || "developer";
+        }
+        await rl.close();
+    }
+    if (!feature) {
+        throw new Error("Missing --feature");
+    }
+    if (!role) {
+        role = "developer";
+    }
+    const safeRole = role.trim().toLowerCase();
+    const date = isoDate();
+    const fileName = `${date}-${node_path_1.default.basename(feature, node_path_1.default.extname(feature))}-${safeRole}.md`;
+    const handoffPath = node_path_1.default.join(projectRoot, ".levit", "handoff", fileName);
+    const content = `# Agent Handoff\n\n- **Date**: ${date}\n- **Role**: ${safeRole}\n- **Feature**: ${feature}\n\n## What to read first\n- SOCIAL_CONTRACT.md\n- .levit/AGENT_ONBOARDING.md\n- ${feature}\n\n## Boundaries\nFollow the Boundaries section of the feature spec strictly.\n\n## Deliverables\n- A minimal, atomic diff\n- A short summary: what changed + why\n- How to verify (commands to run)\n- Open questions / risks\n\n## Review protocol\nFollow: .levit/workflows/submit-for-review.md\n`;
+    (0, write_file_1.writeTextFile)(handoffPath, content, { overwrite });
+    process.stdout.write(`Created ${node_path_1.default.relative(projectRoot, handoffPath)}\n`);
+}

package/dist/src/commands/index.js

@@ -0,0 +1,11 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.handoffCommand = exports.decisionCommand = exports.featureCommand = exports.initProject = void 0;
+var init_1 = require("./init");
+Object.defineProperty(exports, "initProject", { enumerable: true, get: function () { return init_1.initProject; } });
+var feature_1 = require("./feature");
+Object.defineProperty(exports, "featureCommand", { enumerable: true, get: function () { return feature_1.featureCommand; } });
+var decision_1 = require("./decision");
+Object.defineProperty(exports, "decisionCommand", { enumerable: true, get: function () { return decision_1.decisionCommand; } });
+var handoff_1 = require("./handoff");
+Object.defineProperty(exports, "handoffCommand", { enumerable: true, get: function () { return handoff_1.handoffCommand; } });

package/dist/src/commands/init.js

@@ -42,8 +42,8 @@ function initProject(projectName, targetPath) {
         console.log("");
         console.log("Next steps:");
         console.log(`  1. cd ${projectName}`);
-        console.log("  2. Review SOCIAL_CONTRACT.md to understand the foundations");
-        console.log("  3. Define your first feature in features/README.md");
+        console.log("  2. Read README.md for the Human Operator Guide");
+        console.log("  3. Onboard your AI in .levit/AGENT_ONBOARDING.md");
         console.log("");
     }
     catch (error) {

package/dist/src/core/cli_args.js

@@ -0,0 +1,35 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parseArgs = parseArgs;
+exports.getStringFlag = getStringFlag;
+exports.getBooleanFlag = getBooleanFlag;
+function parseArgs(args) {
+    const positional = [];
+    const flags = {};
+    for (let i = 0; i < args.length; i += 1) {
+        const token = args[i];
+        if (!token.startsWith("--")) {
+            positional.push(token);
+            continue;
+        }
+        const key = token.slice(2);
+        const next = args[i + 1];
+        if (!next || next.startsWith("--")) {
+            flags[key] = true;
+            continue;
+        }
+        flags[key] = next;
+        i += 1;
+    }
+    return { positional, flags };
+}
+function getStringFlag(flags, key) {
+    const v = flags[key];
+    if (typeof v === "string") {
+        return v;
+    }
+    return undefined;
+}
+function getBooleanFlag(flags, key) {
+    return flags[key] === true;
+}

package/dist/src/core/ids.js

@@ -0,0 +1,34 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.nextSequentialId = nextSequentialId;
+const fs_extra_1 = __importDefault(require("fs-extra"));
+/**
+ * Finds the next sequential 3-digit ID in a directory based on a filename pattern.
+ *
+ * @param directory The directory to scan
+ * @param pattern A regex with a single capture group for the ID number
+ * @returns The next ID as a zero-padded string (e.g., "001")
+ */
+function nextSequentialId(directory, pattern) {
+    if (!fs_extra_1.default.existsSync(directory)) {
+        return "001";
+    }
+    const files = fs_extra_1.default.readdirSync(directory);
+    let max = 0;
+    for (const f of files) {
+        const m = f.match(pattern);
+        if (!m) {
+            continue;
+        }
+        const n = Number.parseInt(m[1], 10);
+        if (!Number.isFinite(n)) {
+            continue;
+        }
+        max = Math.max(max, n);
+    }
+    const next = max + 1;
+    return String(next).padStart(3, "0");
+}

package/dist/src/core/levit_project.js

@@ -0,0 +1,30 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.findLevitProjectRoot = findLevitProjectRoot;
+exports.requireLevitProjectRoot = requireLevitProjectRoot;
+const fs_extra_1 = __importDefault(require("fs-extra"));
+const node_path_1 = __importDefault(require("node:path"));
+function findLevitProjectRoot(startDir) {
+    let current = node_path_1.default.resolve(startDir);
+    while (true) {
+        const marker = node_path_1.default.join(current, ".levit", "AGENT_ONBOARDING.md");
+        if (fs_extra_1.default.existsSync(marker)) {
+            return current;
+        }
+        const parent = node_path_1.default.dirname(current);
+        if (parent === current) {
+            return null;
+        }
+        current = parent;
+    }
+}
+function requireLevitProjectRoot(startDir) {
+    const root = findLevitProjectRoot(startDir);
+    if (!root) {
+        throw new Error("Not a levit project (missing .levit/AGENT_ONBOARDING.md). Run this command from a levit-initialized repository.");
+    }
+    return root;
+}

package/dist/src/core/write_file.js

@@ -0,0 +1,15 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.writeTextFile = writeTextFile;
+const fs_extra_1 = __importDefault(require("fs-extra"));
+const node_path_1 = __importDefault(require("node:path"));
+function writeTextFile(targetPath, content, options) {
+    fs_extra_1.default.ensureDirSync(node_path_1.default.dirname(targetPath));
+    if (fs_extra_1.default.existsSync(targetPath) && !options.overwrite) {
+        throw new Error(`File already exists: ${targetPath}`);
+    }
+    fs_extra_1.default.writeFileSync(targetPath, content, "utf8");
+}

package/dist/tests/init.test.js

@@ -13,6 +13,9 @@ const init_1 = require("../src/commands/init");
 function exists(p) {
     return node_fs_1.default.existsSync(p);
 }
+function getCliPath() {
+    return node_path_1.default.join(process.cwd(), "dist", "bin", "cli.js");
+}
 (0, node_test_1.default)("levit init copies default template exactly", () => {
     const tempDir = node_fs_1.default.mkdtempSync(node_path_1.default.join(node_os_1.default.tmpdir(), "levit-kit-test-"));
     const projectName = "test-project";
@@ -28,13 +31,24 @@ function exists(p) {
     node_assert_1.default.ok(exists(node_path_1.default.join(projectPath, "pipelines")));
     node_assert_1.default.ok(exists(node_path_1.default.join(projectPath, "docs")));
     node_assert_1.default.ok(exists(node_path_1.default.join(projectPath, "roles", "README.md")), "Roles README should exist");
-    // New files assertions
+    // AIDD assertions
+    node_assert_1.default.ok(exists(node_path_1.default.join(projectPath, ".levit")), ".levit directory should exist");
+    node_assert_1.default.ok(exists(node_path_1.default.join(projectPath, ".levit", "AGENT_ONBOARDING.md")), "AGENT_ONBOARDING.md should exist");
+    node_assert_1.default.ok(exists(node_path_1.default.join(projectPath, ".levit", "decision-record.md")), "decision-record.md should exist");
+    node_assert_1.default.ok(exists(node_path_1.default.join(projectPath, ".levit", "workflows", "example-task.md")), "Example workflow should exist");
+    node_assert_1.default.ok(exists(node_path_1.default.join(projectPath, ".levit", "workflows", "submit-for-review.md")), "Submit for review workflow should exist");
+    node_assert_1.default.ok(exists(node_path_1.default.join(projectPath, ".levit", "prompts")), "Prompts directory should exist");
+    node_assert_1.default.ok(exists(node_path_1.default.join(projectPath, ".levit", "prompts", "global-rules.md")), "Global rules should exist");
+    // New folders assertions
+    node_assert_1.default.ok(exists(node_path_1.default.join(projectPath, "evals")), "Evals directory should exist");
+    node_assert_1.default.ok(exists(node_path_1.default.join(projectPath, "evals", "README.md")), "Evals README should exist");
     node_assert_1.default.ok(exists(node_path_1.default.join(projectPath, ".gitignore")), ".gitignore should exist");
     node_assert_1.default.ok(exists(node_path_1.default.join(projectPath, "package.json")), "package.json should exist");
     // Agent boundaries
     node_assert_1.default.ok(exists(node_path_1.default.join(projectPath, "agents", "AGENTS.md")), "Agent guidelines should exist");
     // Feature contract
     node_assert_1.default.ok(exists(node_path_1.default.join(projectPath, "features", "README.md")), "Feature README should exist");
+    node_assert_1.default.ok(exists(node_path_1.default.join(projectPath, "features", "INTENT.md")), "Feature INTENT template should exist");
     // Clean up
     node_fs_1.default.rmSync(tempDir, { recursive: true, force: true });
 });
@@ -43,6 +57,59 @@ function exists(p) {
     node_assert_1.default.ok(output.includes("Usage: levit [command] [options]"));
     node_assert_1.default.ok(output.includes("init <project-name>"));
 });
+(0, node_test_1.default)("CLI feature new creates a feature intent file", () => {
+    const tempDir = node_fs_1.default.mkdtempSync(node_path_1.default.join(node_os_1.default.tmpdir(), "levit-kit-test-"));
+    const projectName = "test-project";
+    const projectPath = node_path_1.default.join(tempDir, projectName);
+    (0, init_1.initProject)(projectName, projectPath);
+    const cliPath = getCliPath();
+    (0, node_child_process_1.execSync)(`node ${cliPath} feature new --yes --id 001 --title "My Feature" --slug my-feature`, { cwd: projectPath });
+    node_assert_1.default.ok(exists(node_path_1.default.join(projectPath, "features", "001-my-feature.md")));
+    node_fs_1.default.rmSync(tempDir, { recursive: true, force: true });
+});
+(0, node_test_1.default)("CLI feature new auto-assigns id when omitted", () => {
+    const tempDir = node_fs_1.default.mkdtempSync(node_path_1.default.join(node_os_1.default.tmpdir(), "levit-kit-test-"));
+    const projectName = "test-project";
+    const projectPath = node_path_1.default.join(tempDir, projectName);
+    (0, init_1.initProject)(projectName, projectPath);
+    const cliPath = getCliPath();
+    (0, node_child_process_1.execSync)(`node ${cliPath} feature new --yes --title "My Feature" --slug my-feature`, { cwd: projectPath });
+    node_assert_1.default.ok(exists(node_path_1.default.join(projectPath, "features", "001-my-feature.md")));
+    node_fs_1.default.rmSync(tempDir, { recursive: true, force: true });
+});
+(0, node_test_1.default)("CLI decision new creates a decision record", () => {
+    const tempDir = node_fs_1.default.mkdtempSync(node_path_1.default.join(node_os_1.default.tmpdir(), "levit-kit-test-"));
+    const projectName = "test-project";
+    const projectPath = node_path_1.default.join(tempDir, projectName);
+    (0, init_1.initProject)(projectName, projectPath);
+    const cliPath = getCliPath();
+    (0, node_child_process_1.execSync)(`node ${cliPath} decision new --yes --id 001 --title "Choose DB" --feature features/001-some-feature.md`, { cwd: projectPath });
+    node_assert_1.default.ok(exists(node_path_1.default.join(projectPath, ".levit", "decisions")));
+    node_assert_1.default.ok(exists(node_path_1.default.join(projectPath, ".levit", "decisions", "ADR-001-choose-db.md")));
+    node_fs_1.default.rmSync(tempDir, { recursive: true, force: true });
+});
+(0, node_test_1.default)("CLI decision new auto-assigns id when omitted", () => {
+    const tempDir = node_fs_1.default.mkdtempSync(node_path_1.default.join(node_os_1.default.tmpdir(), "levit-kit-test-"));
+    const projectName = "test-project";
+    const projectPath = node_path_1.default.join(tempDir, projectName);
+    (0, init_1.initProject)(projectName, projectPath);
+    const cliPath = getCliPath();
+    (0, node_child_process_1.execSync)(`node ${cliPath} decision new --yes --title "Auto ID Decision"`, { cwd: projectPath });
+    node_assert_1.default.ok(exists(node_path_1.default.join(projectPath, ".levit", "decisions", "ADR-001-auto-id-decision.md")));
+    node_fs_1.default.rmSync(tempDir, { recursive: true, force: true });
+});
+(0, node_test_1.default)("CLI handoff new creates an agent handoff brief", () => {
+    const tempDir = node_fs_1.default.mkdtempSync(node_path_1.default.join(node_os_1.default.tmpdir(), "levit-kit-test-"));
+    const projectName = "test-project";
+    const projectPath = node_path_1.default.join(tempDir, projectName);
+    (0, init_1.initProject)(projectName, projectPath);
+    const cliPath = getCliPath();
+    (0, node_child_process_1.execSync)(`node ${cliPath} handoff new --yes --feature features/001-some-feature.md --role security`, { cwd: projectPath });
+    const handoffDir = node_path_1.default.join(projectPath, ".levit", "handoff");
+    node_assert_1.default.ok(exists(handoffDir));
+    node_assert_1.default.ok(node_fs_1.default.readdirSync(handoffDir).some((f) => f.endsWith("-security.md")));
+    node_fs_1.default.rmSync(tempDir, { recursive: true, force: true });
+});
 (0, node_test_1.default)("CLI --version works", () => {
     const output = (0, node_child_process_1.execSync)("node dist/bin/cli.js --version").toString();
     node_assert_1.default.ok(output.startsWith("levit-kit v"));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@buba_71/levit",
-  "version": "0.3.4",
+  "version": "0.4.0",
   "description": "Hybrid starter kit for Antigravity projects",
   "author": "David BUBA",
   "license": "MIT",

package/templates/default/.levit/AGENT_ONBOARDING.md

@@ -0,0 +1,28 @@
+# AGENT_ONBOARDING.md
+
+> [!IMPORTANT]
+> **To the AI Agent reading this**: You are entering a project governed by the **Levit-Kit** protocol. This document is your operating manual for this specific environment.
+
+## 1. Project Essence
+This project is a hybrid workspace where humans define intentions and AI ensures execution.
+- **Human Role**: Vision, decision-making, final validation.
+- **AI Role (You)**: Implementation, proactive suggestions, technical consistency.
+
+## 2. Navigation & Context
+To understand this project quickly, explore in this order:
+1.  `SOCIAL_CONTRACT.md`: Your ethical and operational boundaries.
+2.  `features/README.md`: The roadmap and logic of what we are building.
+3.  `agents/AGENTS.md`: Specific definitions of other roles if they exist.
+4.  `.levit/workflows/`: Step-by-step guides for common tasks.
+
+## 3. Rules of Engagement
+- **Transparency**: If you are unsure about a decision, ask the human. Do not "hallucinate" architectural choices.
+- **Atomicity**: Keep your edits small and focused.
+- **Traceability**: Every major change should be linked to a feature defined in `features/`.
+- **Tests First**: Before submitting a complex change, check if tests exist in `tests/` and run them.
+
+## 4. How to use Workflows
+Check `.levit/workflows/` before starting a task. If a workflow like `add-logic.md` exists, follow its steps strictly to maintain project harmony.
+
+---
+*Generated by Levit-Kit - Elevating Human-AI Collaboration.*

package/templates/default/.levit/decision-record.md

@@ -0,0 +1,19 @@
+# Decision Record: [Title of the Decision]
+
+- **Date**: [YYYY-MM-DD]
+- **Status**: [Draft / Proposed / Approved]
+
+## Context
+What is the problem we are solving? What are the constraints?
+
+## Decision
+What is the chosen solution? How does it solve the problem?
+
+## Rationale
+Why did we choose this? (e.g., performance, simplicity, maintainability, cost)
+
+## Alternatives Considered
+What was rejected and why?
+
+## Consequences
+What are the trade-offs? What are the next steps?

package/templates/default/.levit/prompts/global-rules.md

@@ -0,0 +1,10 @@
+# Project Standards & Global Rules
+
+> [!NOTE]
+> These rules are defaults provided by Levit-Kit. Feel free to adapt them to your specific tech stack.
+
+1.  **Strict Typing**: Prioritize strong typing and explicit interfaces over dynamic types.
+2.  **Documentation**: Every core function or business logic should include descriptive comments.
+3.  **Atomicity**: One task = one intent = one atomic implementation.
+4.  **No Hallucinations**: Do not assume the existence of external dependencies. Verify the environment before using a library.
+5.  **Quality First**: Follow the project's architectural patterns (SOLID, modularity).

package/templates/default/.levit/prompts/refactoring-guidelines.md

@@ -0,0 +1,9 @@
+# Refactoring Guidelines
+
+Follow these steps when task involves cleaning or refactoring existing code.
+
+1.  **Analyze**: Run tests before changing anything.
+2.  **Protect**: Identify the critical path of the logic.
+3.  **Iterate**: Make small, verifiable changes.
+4.  **Verify**: Re-run tests and run the `conformance.eval.ts`.
+5.  **Document**: Update `SOCIAL_CONTRACT.md` if the refactoring changes a core principle.

package/templates/default/.levit/workflows/example-task.md

@@ -0,0 +1,9 @@
+# Workflow: Example Task
+
+This is a placeholder for a cognitive workflow. 
+
+## Steps
+1. **Research**: Analyze the current file.
+2. **Propose**: Suggest the change.
+3. **Implement**: Code the solution.
+4. **Verify**: Run tests.

package/templates/default/.levit/workflows/submit-for-review.md

@@ -0,0 +1,18 @@
+# Workflow: Submit for Review
+
+When you have finished a task, follow these steps to hand over to the Human:
+
+1. **Self-Verification**:
+   - Ensure you haven't broken any principle from `SOCIAL_CONTRACT.md`.
+   - Verify that your code is atomic and follows naming conventions.
+   - Run existing tests and ensure they pass.
+
+2. **The "Handover" Message**:
+   Provide a summary to the Human containing:
+   - **What changed**: A bullet-point list of modifications.
+   - **Verification**: How did you test it? (CLI output, test logs, etc.).
+   - **Next Steps**: What should the human do or check now?
+   - **Open Questions**: Are there any remaining uncertainties or technical debt?
+
+3. **Status Update**:
+   Mark the task as completed in the relevant feature file or task tracker.

package/templates/default/README.md

@@ -1,16 +1,35 @@
 # Project Overview
 
-This project was initialized with **levit-kit**.
+This project was initialized with **Levit-Kit**. 
+It is designed for a **hybrid workspace** where Human vision leads and AI execution follows.
 
-Its purpose is to provide a **clear, predictable structure**
-for working with humans and AI agents.
+## 🚀 Quick Start: Human Operator Guide
 
-This repository:
-- contains no business logic
-- imposes no workflow
-- makes no automated decisions
+### 1. The Day One Setup
+- **Adjust Governance**: Open `SOCIAL_CONTRACT.md` and tweak the principles to match your vision.
+- **Define Standards**: Open `.levit/prompts/global-rules.md` to set your technical expectations (language, styling, strictness).
 
-Start by reading:
-- SOCIAL_CONTRACT.md
-- agents/AGENTS.md
-- features/README.md
+### 2. The "Intent-First" Workflow
+When building a new feature, do not start with code:
+1.  **Declare Intent**: Copy `features/INTENT.md` to a new file (e.g., `features/001-my-feature.md`).
+2.  **Define Boundaries**: Fill in the "User Story" and especially the "Boundaries" section (what the AI must NOT touch).
+
+### 3. Leading your Agents
+When using an AI agent (Antigravity, Cursor, etc.):
+1.  **Onboard the Agent**: Direct it to read `.levit/AGENT_ONBOARDING.md` in your first prompt.
+2.  **Assign the Task**: Point it to your new intent file in `features/`.
+3.  **Review the Output**: Follow the guides in `.levit/workflows/submit-for-review.md`.
+
+---
+
+## 🏛️ Project Principles
+This repository is built for **clarity over automation**:
+- **Explicit Structure**: No hidden magic.
+- **Human Sovereignty**: You make the final decisions.
+- **Traceability**: All technical choices are documented (see `.levit/decision-record.md`).
+
+## 📂 Navigation
+- `SOCIAL_CONTRACT.md`: Your ethical and operational foundations.
+- `.levit/`: The AI's workspace (Onboarding, Prompts, Workflows).
+- `features/`: The project roadmap and active intents.
+- `evals/`: Technical quality tests for AI outputs.

package/templates/default/SOCIAL_CONTRACT.md

@@ -8,6 +8,11 @@ This project follows the levit-kit social contract.
 - Agents are assistants, not decision-makers
 - Structure is explicit
 - Conventions are preferred over configuration
+- **Agents (AI) are onboarded through specific protocols**
+
+## Agent (AI) Role
+
+This project is AI-friendly. Agents must follow the instructions located in `.levit/AGENT_ONBOARDING.md`.
 
 ## What this project does not do
 

package/templates/default/evals/README.md

@@ -0,0 +1,14 @@
+# Evaluations (Evals)
+
+This directory is dedicated to testing the **intentions** and the **quality** of the AI output, rather than just the code implementation.
+
+## Why Evals?
+While unit tests verify if the code works (logic), Evals verify if the AI respected the "Social Contract" and the "Human Intent".
+
+## Example Evals
+- **Conformance**: Does the generated code follow our naming conventions?
+- **Security**: Did the AI introduce any obvious secret leaks in the prompts?
+- **Compliance**: Does the output still match the rules in `.levit/AGENT_ONBOARDING.md`?
+
+---
+*Verify then Trust.*

package/templates/default/evals/conformance.eval.ts

@@ -0,0 +1,16 @@
+/**
+ * Example Conformance Evaluation
+ * 
+ * This is a placeholder for an evaluation script.
+ * In a real-world scenario, you would use a library like Promptfoo or Giskard
+ * to run these evaluations against your agent's outputs.
+ */
+
+export const conformanceEval = {
+  name: "Social Contract Adherence",
+  criteria: [
+    "Does the code follow camelCase for variables?",
+    "Is every change linked to an entry in features/?",
+    "Does the AI avoid modifying files outside its boundaries?"
+  ]
+};

package/templates/default/features/INTENT.md

@@ -0,0 +1,23 @@
+# INTENT: [Feature Name]
+
+> Copy this file to create a new feature specification.
+
+## 1. Vision (The "Why")
+- **User Story**: As a [role], I want to [action], so that [value].
+- **Priority**: [Low / Medium / High / Critical]
+
+## 2. Success Criteria (The "What")
+What must be true for this feature to be considered "Done"?
+- [ ] Criterion 1
+- [ ] Criterion 2
+
+## 3. Boundaries (The "No")
+What is explicitly **OUT OF SCOPE** for this iteration? Prevents scope creep.
+- Non-goal 1
+- Non-goal 2
+
+## 4. Technical Constraints
+- Specific tech, rules, or patterns to follow.
+
+## 5. Agent Task
+Specific starting point for the AI (e.g., "Implement the API endpoint first").

package/templates/default/features/README.md

@@ -1,12 +1,11 @@
 # Features
 
-A feature is a **contract**, not an implementation.
+This directory contains the roadmap and the active specifications of the project.
 
-Each feature document should define:
-- intent
-- inputs
-- outputs
-- constraints
+## How to add a feature
+1. Copy [INTENT.md](./INTENT.md) to a new file (e.g., `001-my-feature.md`).
+2. Fill the "Human Intent" sections.
+3. Let the Agent implement the technical details.
 
-Features are discussed and validated here.
-Implementation happens elsewhere.
+---
+📄 Refer to [.levit/AGENT_ONBOARDING.md](../.levit/AGENT_ONBOARDING.md) for collaboration guidelines.

package/templates/default/package.json

@@ -0,0 +1,11 @@
+{
+  "name": "project-name",
+  "version": "0.1.0",
+  "private": true,
+  "scripts": {
+    "test": "node --test",
+    "eval": "ts-node evals/conformance.eval.ts"
+  },
+  "dependencies": {},
+  "devDependencies": {}
+}