@pedrocivita/tocket 1.0.0 → 1.2.0

package/README.md

@@ -1,38 +1,110 @@
+![CI](https://github.com/pedrocivita/tocket/actions/workflows/ci.yml/badge.svg)
+[![npm](https://img.shields.io/npm/v/@pedrocivita/tocket)](https://www.npmjs.com/package/@pedrocivita/tocket)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+
 # Tocket
 
 **The Context Engineering Framework for Multi-Agent Workspaces**
 
-Tocket structures how AI agents share context, hand off work, and build on each other's output. It turns ad-hoc prompting into a repeatable engineering workflow.
+When multiple AI agents work on the same codebase, context is lost between sessions and between agents. Each one starts from scratch, re-reads files, and makes decisions that conflict with previous ones.
 
-## Core Pillars
+Tocket fixes this with two primitives:
 
-- **Triangulation** — Architect + Executor pattern. One agent plans, another implements, with structured handoff payloads between them.
-- **Context as Code** — Memory Bank protocol. Project context lives in version-controlled files (`.context/`), not ephemeral chat history.
+- **Memory Bank** — A `.context/` directory with version-controlled markdown files that any AI can read. The project's ground truth lives in files, not in chat history.
+- **Triangulation** — An Architect plans, an Executor implements, and structured XML payloads are the handoff between them.
 
-## Commands
+## Who is this for?
+
+- Developers using **multi-agent setups** (Gemini + Claude, Cursor + Copilot, etc.)
+- Teams that want **reproducible AI-assisted development** across sessions
+- Anyone tired of re-explaining project context to AI every time they open a chat
+
+## You don't need the CLI to use Tocket
 
-| Command | Description |
-|---------|-------------|
-| `tocket init` | Scaffold an agentic workspace with Memory Bank and triangulation config |
-| `tocket generate` | Build payload XMLs interactively for Architect-Executor handoff |
-| `tocket sync` | Update Memory Bank from git history and session artifacts |
+The protocol is just files. You can adopt it manually:
 
-## Installation
+1. Create a `.context/` directory with `activeContext.md` and `systemPatterns.md`
+2. Add a `TOCKET.md` to your repo root (see [the spec](TOCKET.md))
+3. Tell your AI agents to read `.context/` before acting
+
+The CLI just automates the scaffolding.
+
+## Quick Start
 
 ```bash
-npx @pedrocivita/tocket
+# Scaffold a new workspace (creates .context/, TOCKET.md, CLAUDE.md, GEMINI.md)
+npx @pedrocivita/tocket init
+
+# Generate a payload XML for agent handoff
+npx @pedrocivita/tocket generate
+
+# Sync session progress into Memory Bank
+npx @pedrocivita/tocket sync
 ```
 
-## Development
+## Commands
 
-```bash
-git clone https://github.com/pedrocivita/tocket.git
-cd tocket
-npm install
-npm run build
-node dist/index.js --help
+| Command           | What it does                                                   |
+| ----------------- | -------------------------------------------------------------- |
+| `tocket init`     | Scaffolds `.context/`, `TOCKET.md`, `CLAUDE.md`, `GEMINI.md`   |
+| `tocket generate` | Interactive payload XML builder — copies to clipboard          |
+| `tocket sync`     | Appends session summary + git log to `.context/progress.md`    |
+| `tocket validate` | Checks if the current directory has a valid Tocket Memory Bank |
+
+## How Triangulation works
+
+```
+Architect (any planning AI)         Executor (any coding AI)
+     │                                   │
+     │  1. Reads .context/               │
+     │  2. Analyzes task                 │
+     │  3. Generates <payload> XML       │
+     │──────── structured handoff ──────►│
+     │                                   │  4. Reads .context/ + payload
+     │                                   │  5. Implements tasks
+     │                                   │  6. Updates .context/
+     │◄──────── status report ───────────│
 ```
 
+The Architect doesn't write code. The Executor doesn't make architecture decisions. The payload is the contract between them.
+
+## Memory Bank files
+
+```
+.context/
+  activeContext.md    ← Current focus. Read this first.
+  systemPatterns.md   ← Architecture decisions and conventions.
+  techContext.md      ← Stack, build tools, critical rules.
+  productContext.md   ← What the product is and why it exists.
+  progress.md         ← What's done, what's next.
+```
+
+All files are markdown. All files are committed to git. Any AI that can read files can participate.
+
+## Documentation
+
+| Guide                                       | Description                                     |
+| ------------------------------------------- | ----------------------------------------------- |
+| [Getting Started](docs/GETTING_STARTED.md)  | Set up your first Tocket workspace in 5 minutes |
+| [Tocket Rules](docs/TOCKET_RULES.md)        | Complete reference for all protocol rules       |
+| [Developer Guide](docs/DEVELOPERS_GUIDE.md) | Contributing to the Tocket CLI codebase         |
+| [Protocol Spec](TOCKET.md)                  | The agent-agnostic protocol specification       |
+
+## How is this different from...
+
+| Tool             | What it does                         | How Tocket differs                                                                   |
+| ---------------- | ------------------------------------ | ------------------------------------------------------------------------------------ |
+| `.cursorrules`   | Single-agent instructions for Cursor | Tocket defines _inter-agent_ protocol, not just single-agent rules                   |
+| `CLAUDE.md`      | Instructions for Claude Code         | Tocket generates `CLAUDE.md` _as part of_ a broader multi-agent system               |
+| `AGENTS.md`      | Codex agent instructions             | Same idea for one agent; Tocket coordinates multiple agents                          |
+| Prompt templates | Static prompts for LLMs              | Tocket's Memory Bank evolves with the project; payloads are structured, not freeform |
+
+## Contributing
+
+We welcome contributions! Please read our [Contributing Guide](CONTRIBUTING.md) to get started.
+
+This project follows a [Code of Conduct](CODE_OF_CONDUCT.md).
+
 ## License
 
 MIT

package/dist/commands/generate.cmd.js

@@ -1,43 +1,31 @@
-import { input, select, number } from "@inquirer/prompts";
+import { input, select } from "@inquirer/prompts";
 import clipboard from "clipboardy";
-function inferMode(score) {
-    if (score <= 6)
-        return "solo";
-    if (score <= 10)
-        return "team-small";
-    return "team-full";
-}
 function buildPayloadXml(opts) {
-    const mode = inferMode(opts.complexity);
-    const skillLines = opts.skills
-        .split(",")
-        .map((s) => s.trim())
-        .filter(Boolean)
-        .map((s) => `      <skill>${s}</skill>`)
-        .join("\n");
-    return `<payload version="3.0">
+    const skillsAttr = opts.skills.trim()
+        ? `\n    <skills>${opts.skills.trim()}</skills>`
+        : "";
+    return `<payload version="2.0">
   <meta>
     <intent>${opts.intent}</intent>
-    <scope>${opts.scope}</scope>
+    <scope>${opts.scope}</scope>${skillsAttr}
     <priority>${opts.priority}</priority>
-    <complexity score="${opts.complexity}" mode="${mode}" />
-    <model>${opts.model}</model>
   </meta>
 
-  <skills>
-${skillLines || "      <!-- Add skills here -->"}
-  </skills>
-
   <context>
-    <!-- Provide relevant context for the Architect -->
+    <summary><!-- Background and reasoning --></summary>
   </context>
 
   <tasks>
-    <!-- The Architect will populate tasks based on the intent -->
+    <task id="1" type="create | edit | delete">
+      <target><!-- file/path --></target>
+      <action><!-- What to do --></action>
+      <spec><!-- Detailed specification --></spec>
+      <done><!-- Definition of done --></done>
+    </task>
   </tasks>
 
   <validate>
-    <!-- Define acceptance criteria -->
+    <check><!-- How to verify success --></check>
   </validate>
 </payload>`;
 }
@@ -57,33 +45,10 @@ export function registerGenerateCommand(program) {
             ],
         });
         const skills = await input({
-            message: "Skills/plugins (comma-separated):",
-        });
-        const model = await select({
-            message: "Architect model:",
-            choices: [
-                {
-                    value: "gemini-3.1-pro-preview-customtools",
-                    name: "gemini-3.1-pro-preview-customtools (default)",
-                },
-                { value: "gemini-2.5-pro", name: "gemini-2.5-pro" },
-            ],
-        });
-        const complexity = await number({
-            message: "Complexity score (0-15):",
-            min: 0,
-            max: 15,
-            required: true,
-        });
-        const xml = buildPayloadXml({
-            intent,
-            scope,
-            priority,
-            skills,
-            model,
-            complexity: complexity ?? 0,
+            message: "Skills/plugins (comma-separated, optional):",
         });
+        const xml = buildPayloadXml({ intent, scope, priority, skills });
         clipboard.writeSync(xml);
-        console.log("\n\x1b[32m✓\x1b[0m Payload XML (v3.0) copied to clipboard! Paste it into your Architect to continue.");
+        console.log("\n\x1b[32m\u2713\x1b[0m Payload XML (v2.0) copied to clipboard! Paste it into your Architect to continue.");
     });
 }

package/dist/commands/init.cmd.js

@@ -1,27 +1,171 @@
 import { input } from "@inquirer/prompts";
-import { mkdir, writeFile } from "node:fs/promises";
+import { mkdir, readFile, writeFile, access } from "node:fs/promises";
 import { join } from "node:path";
-import { claudeMd, geminiMd, activeContextMd, systemPatternsMd, } from "../templates/memory-bank.js";
+import { claudeMd, geminiMd, tocketMd, activeContextMd, systemPatternsMd, productContextMd, techContextMd, progressMd, cursorrulesMd, } from "../templates/memory-bank.js";
+async function fileExists(path) {
+    try {
+        await access(path);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function detectFramework(deps, devDeps) {
+    const all = [...deps, ...devDeps];
+    if (all.includes("next"))
+        return "Next.js";
+    if (all.includes("nuxt"))
+        return "Nuxt";
+    if (all.includes("@sveltejs/kit"))
+        return "SvelteKit";
+    if (all.includes("remix") || all.includes("@remix-run/react"))
+        return "Remix";
+    if (all.includes("astro"))
+        return "Astro";
+    if (all.includes("react"))
+        return "React";
+    if (all.includes("vue"))
+        return "Vue";
+    if (all.includes("svelte"))
+        return "Svelte";
+    if (all.includes("angular") || all.includes("@angular/core"))
+        return "Angular";
+    if (all.includes("express"))
+        return "Express";
+    if (all.includes("fastify"))
+        return "Fastify";
+    if (all.includes("hono"))
+        return "Hono";
+    if (all.includes("commander") || all.includes("yargs"))
+        return "CLI (Node.js)";
+    return "";
+}
+function detectBuild(devDeps) {
+    if (devDeps.includes("vite"))
+        return "Vite";
+    if (devDeps.includes("webpack"))
+        return "Webpack";
+    if (devDeps.includes("esbuild"))
+        return "esbuild";
+    if (devDeps.includes("rollup"))
+        return "Rollup";
+    if (devDeps.includes("turbopack") || devDeps.includes("turbo"))
+        return "Turbopack";
+    if (devDeps.includes("typescript"))
+        return "tsc";
+    return "";
+}
+function pickExtras(deps, devDeps) {
+    const notable = [
+        "tailwindcss", "prisma", "@prisma/client",
+        "drizzle-orm", "mongoose", "sequelize",
+        "trpc", "@trpc/server", "graphql",
+        "zod", "joi", "yup",
+        "jest", "vitest", "mocha",
+        "eslint", "prettier", "biome",
+        "docker-compose", "firebase", "supabase",
+        "stripe", "clerk", "@clerk/nextjs",
+        "socket.io", "redis", "bullmq",
+    ];
+    const all = [...deps, ...devDeps];
+    return notable.filter((n) => all.includes(n));
+}
+async function detectStack(cwd) {
+    const empty = {
+        language: "",
+        runtime: "",
+        build: "",
+        framework: "",
+        extras: [],
+    };
+    const pkgPath = join(cwd, "package.json");
+    if (!(await fileExists(pkgPath))) {
+        return { stack: empty, detectedName: "", detectedDescription: "" };
+    }
+    let pkg;
+    try {
+        const raw = await readFile(pkgPath, "utf-8");
+        pkg = JSON.parse(raw);
+    }
+    catch {
+        return { stack: empty, detectedName: "", detectedDescription: "" };
+    }
+    const deps = Object.keys(pkg.dependencies ?? {});
+    const devDeps = Object.keys(pkg.devDependencies ?? {});
+    const hasTsConfig = await fileExists(join(cwd, "tsconfig.json"));
+    const hasTs = hasTsConfig || devDeps.includes("typescript");
+    const stack = {
+        language: hasTs ? "TypeScript" : "JavaScript",
+        runtime: "Node.js",
+        build: detectBuild(devDeps),
+        framework: detectFramework(deps, devDeps),
+        extras: pickExtras(deps, devDeps),
+    };
+    const rawName = pkg.name ?? "";
+    const detectedName = rawName.startsWith("@")
+        ? rawName.split("/").pop() ?? rawName
+        : rawName;
+    return {
+        stack,
+        detectedName,
+        detectedDescription: pkg.description ?? "",
+    };
+}
 export function registerInitCommand(program) {
     program
         .command("init")
         .description("Scaffold an agentic workspace with Memory Bank and triangulation config")
         .action(async () => {
-        const projectName = await input({ message: "Project Name:" });
-        const description = await input({ message: "Short Description:" });
-        const contextDir = join(process.cwd(), ".context");
+        const cwd = process.cwd();
+        const { stack, detectedName, detectedDescription } = await detectStack(cwd);
+        const hasDetection = Boolean(stack.language);
+        if (hasDetection) {
+            console.log("\n  Auto-detected stack from package.json:");
+            if (stack.language)
+                console.log(`    Language:  ${stack.language}`);
+            if (stack.runtime)
+                console.log(`    Runtime:   ${stack.runtime}`);
+            if (stack.build)
+                console.log(`    Build:     ${stack.build}`);
+            if (stack.framework)
+                console.log(`    Framework: ${stack.framework}`);
+            if (stack.extras.length)
+                console.log(`    Extras:    ${stack.extras.join(", ")}`);
+            console.log();
+        }
+        const projectName = await input({
+            message: "Project Name:",
+            default: detectedName || undefined,
+        });
+        const description = await input({
+            message: "Short Description:",
+            default: detectedDescription || undefined,
+        });
+        const contextDir = join(cwd, ".context");
         await mkdir(contextDir, { recursive: true });
         const files = [
+            ["TOCKET.md", tocketMd(projectName)],
             ["CLAUDE.md", claudeMd(projectName, description)],
             ["GEMINI.md", geminiMd(projectName, description)],
+            [".cursorrules", cursorrulesMd(projectName, description)],
             [join(".context", "activeContext.md"), activeContextMd(projectName)],
             [join(".context", "systemPatterns.md"), systemPatternsMd(projectName)],
+            [
+                join(".context", "productContext.md"),
+                productContextMd(projectName, description),
+            ],
+            [
+                join(".context", "techContext.md"),
+                techContextMd(projectName, hasDetection ? stack : undefined),
+            ],
+            [join(".context", "progress.md"), progressMd(projectName)],
         ];
         for (const [filePath, content] of files) {
-            const fullPath = join(process.cwd(), filePath);
+            const fullPath = join(cwd, filePath);
             await writeFile(fullPath, content, "utf-8");
             console.log(`  created ${filePath}`);
         }
-        console.log(`\nAgentic workspace initialized for ${projectName}! Ready to launch.`);
+        console.log(`\nAgentic workspace initialized for ${projectName}!${hasDetection ? " Stack pre-populated from package.json." : ""} Ready to launch.`);
     });
 }

package/dist/commands/validate.cmd.d.ts

@@ -0,0 +1,2 @@
+import type { Command } from "commander";
+export declare function registerValidateCommand(program: Command): void;

package/dist/commands/validate.cmd.js

@@ -0,0 +1,90 @@
+import { existsSync, statSync } from "node:fs";
+import { join } from "node:path";
+const PASS = "\x1b[32m\u2713\x1b[0m";
+const WARN = "\x1b[33m\u26A0\x1b[0m";
+const FAIL = "\x1b[31m\u2717\x1b[0m";
+function checkFile(basePath, relativePath, required) {
+    const fullPath = join(basePath, relativePath);
+    if (existsSync(fullPath)) {
+        return { icon: PASS, message: `${relativePath} found` };
+    }
+    if (required) {
+        return { icon: FAIL, message: `${relativePath} missing (required)` };
+    }
+    return { icon: WARN, message: `${relativePath} missing (optional)` };
+}
+function checkStale(basePath, relativePath) {
+    const fullPath = join(basePath, relativePath);
+    if (!existsSync(fullPath))
+        return null;
+    const stats = statSync(fullPath);
+    const daysSinceModified = Math.floor((Date.now() - stats.mtimeMs) / (1000 * 60 * 60 * 24));
+    if (daysSinceModified > 7) {
+        return {
+            icon: WARN,
+            message: `${relativePath} last modified ${daysSinceModified} days ago (may be stale)`,
+        };
+    }
+    return null;
+}
+function checkAgentFile(basePath) {
+    const agentFiles = [
+        "CLAUDE.md",
+        "GEMINI.md",
+        "EXECUTOR.md",
+        "ARCHITECT.md",
+        ".cursorrules",
+    ];
+    const found = agentFiles.filter((f) => existsSync(join(basePath, f)));
+    if (found.length > 0) {
+        return {
+            icon: PASS,
+            message: `Agent config found: ${found.join(", ")}`,
+        };
+    }
+    return {
+        icon: WARN,
+        message: "No agent config file found (CLAUDE.md, GEMINI.md, etc.)",
+    };
+}
+export function registerValidateCommand(program) {
+    program
+        .command("validate")
+        .description("Check the health of a Tocket workspace")
+        .action(() => {
+        const cwd = process.cwd();
+        const results = [];
+        let hasFailure = false;
+        console.log("\nValidating Tocket workspace...\n");
+        // Required files
+        results.push(checkFile(cwd, join(".context"), true));
+        results.push(checkFile(cwd, join(".context", "activeContext.md"), true));
+        results.push(checkFile(cwd, join(".context", "systemPatterns.md"), true));
+        results.push(checkFile(cwd, "TOCKET.md", true));
+        // Optional files
+        results.push(checkFile(cwd, join(".context", "techContext.md"), false));
+        results.push(checkFile(cwd, join(".context", "productContext.md"), false));
+        results.push(checkFile(cwd, join(".context", "progress.md"), false));
+        // Agent config
+        results.push(checkAgentFile(cwd));
+        // Staleness check
+        const staleCheck = checkStale(cwd, join(".context", "activeContext.md"));
+        if (staleCheck) {
+            results.push(staleCheck);
+        }
+        // Print results
+        for (const r of results) {
+            console.log(`  ${r.icon} ${r.message}`);
+            if (r.icon === FAIL)
+                hasFailure = true;
+        }
+        console.log("");
+        if (hasFailure) {
+            console.log("\x1b[31mWorkspace has issues.\x1b[0m Run \x1b[1mtocket init\x1b[0m to scaffold missing files.");
+            process.exitCode = 1;
+        }
+        else {
+            console.log("\x1b[32mWorkspace is healthy.\x1b[0m");
+        }
+    });
+}

package/dist/index.js

@@ -3,12 +3,14 @@ import { Command } from "commander";
 import { registerInitCommand } from "./commands/init.cmd.js";
 import { registerGenerateCommand } from "./commands/generate.cmd.js";
 import { registerSyncCommand } from "./commands/sync.cmd.js";
+import { registerValidateCommand } from "./commands/validate.cmd.js";
 const program = new Command();
 program
     .name("tocket")
     .description("The Context Engineering Framework for Multi-Agent Workspaces")
-    .version("1.0.0");
+    .version("1.2.0");
 registerInitCommand(program);
 registerGenerateCommand(program);
 registerSyncCommand(program);
+registerValidateCommand(program);
 program.parse();

package/dist/templates/memory-bank.d.ts

@@ -1,4 +1,16 @@
+export interface StackInfo {
+    language: string;
+    runtime: string;
+    build: string;
+    framework: string;
+    extras: string[];
+}
 export declare const claudeMd: (projectName: string, description: string) => string;
 export declare const geminiMd: (projectName: string, description: string) => string;
 export declare const activeContextMd: (projectName: string) => string;
 export declare const systemPatternsMd: (projectName: string) => string;
+export declare const productContextMd: (projectName: string, description: string) => string;
+export declare const techContextMd: (projectName: string, stack?: StackInfo) => string;
+export declare const progressMd: (projectName: string) => string;
+export declare const cursorrulesMd: (projectName: string, description: string) => string;
+export declare const tocketMd: (projectName: string) => string;

package/dist/templates/memory-bank.js

@@ -53,7 +53,7 @@ Your job is to **analyze, plan, and decide**. You do not write code directly —
 ## Rules
 
 1. **Read \`.context/\` first** — Understand current state before planning.
-2. **Produce mission briefs** — Use \`<mission-brief>\` XML format for handoff to the Executor.
+2. **Produce payloads** — Use \`<payload version="2.0">\` XML format for handoff to the Executor.
 3. **Never write code inline** — Provide specs, not implementations. The Executor handles code.
 4. **Update systemPatterns.md** — When you make architectural decisions, record them.
 5. **Think in constraints** — Define what the system should and should not do.
@@ -70,12 +70,12 @@ Your job is to **analyze, plan, and decide**. You do not write code directly —
 
 ---
 
-## Mission Brief Format
+## Payload Format
 
 \`\`\`xml
-<mission-brief version="1.0">
+<payload version="2.0">
   <meta>
-    <goal>What needs to happen</goal>
+    <intent>What needs to happen</intent>
     <scope>Which files/modules are affected</scope>
     <priority>high | medium | low</priority>
   </meta>
@@ -94,7 +94,7 @@ Your job is to **analyze, plan, and decide**. You do not write code directly —
   <validate>
     <check>Verification step</check>
   </validate>
-</mission-brief>
+</payload>
 \`\`\`
 `;
 export const activeContextMd = (projectName) => `# Active Context - ${projectName}
@@ -139,3 +139,209 @@ _To be defined._
 |----------|-----------|------|
 | Adopted Tocket triangulation | Structured multi-agent workflow | ${new Date().toISOString().split("T")[0]} |
 `;
+export const productContextMd = (projectName, description) => `# Product Context - ${projectName}
+
+<!-- What the product is, who it's for, and why it exists. Updated by the Architect. -->
+
+## What is ${projectName}?
+
+${description || "_Describe your product here._"}
+
+## Problem
+
+_What problem does this project solve?_
+
+## Solution
+
+_How does it solve it?_
+
+## Target Users
+
+_Who is this for?_
+
+## Design Principles
+
+- _List the guiding principles for this project_
+`;
+export const techContextMd = (projectName, stack) => {
+    const lang = stack?.language || "";
+    const rt = stack?.runtime || "";
+    const bld = stack?.build || "";
+    const fw = stack?.framework || "";
+    const extras = stack?.extras?.length
+        ? `\n### Notable Dependencies\n\n${stack.extras.map((d) => `- \`${d}\``).join("\n")}\n`
+        : "";
+    return `# Tech Context - ${projectName}
+
+<!-- Stack, build tools, and critical rules. Updated by the Architect. -->
+
+## Stack
+
+| Layer | Technology | Notes |
+|-------|-----------|-------|
+| Language | ${lang} | ${lang ? "Auto-detected by Tocket" : ""} |
+| Runtime | ${rt} | ${rt ? "Auto-detected by Tocket" : ""} |
+| Build | ${bld} | ${bld ? "Auto-detected by Tocket" : ""} |
+| Framework | ${fw} | ${fw ? "Auto-detected by Tocket" : ""} |
+${extras}
+## Critical Rules
+
+_Document any rules that agents must follow (e.g., import conventions, naming patterns)._
+
+## Project Structure
+
+\`\`\`
+${projectName}/
+  src/         # Source code
+  .context/    # Memory Bank
+\`\`\`
+`;
+};
+export const progressMd = (projectName) => `# Progress Log - ${projectName}
+
+<!-- Appended by tocket sync and manual updates -->
+
+## Milestone: Project Initialization
+
+**Status**: Complete
+
+- [x] Agentic workspace scaffolded with Tocket CLI
+- [x] Memory Bank initialized (\`.context/\`)
+
+## Next Up
+
+- [ ] _Define your first milestone here_
+`;
+export const cursorrulesMd = (projectName, description) => `# .cursorrules - ${projectName}
+
+# Generated by Tocket CLI — compatible with Cursor IDE
+
+## Role
+
+You are the **Executor** for **${projectName}**.
+${description ? `\n> ${description}\n` : ""}
+Your job is to **implement**, not to plan. Read the Memory Bank before every session, follow the Architect's decisions, and write code.
+
+## Rules
+
+1. **Always read \`.context/\` first** — Start every session by reading activeContext.md and systemPatterns.md.
+2. **Follow the Architect's plan** — Implementation decisions come from mission briefs. Do not redesign.
+3. **Ask before deviating** — If the plan is unclear or blocked, ask the user. Do not improvise architecture.
+4. **Write code in English** — Variables, functions, comments, commits — all in \`en-US\`.
+5. **Update Memory Bank on completion** — After finishing a task, update activeContext.md with what changed.
+
+## Memory Bank
+
+| File | Purpose |
+|------|---------|
+| \`.context/activeContext.md\` | Current focus, recent changes, open decisions |
+| \`.context/systemPatterns.md\` | Architecture patterns, tech stack, conventions |
+| \`.context/techContext.md\` | Stack, build tools, critical rules |
+
+## Workflow
+
+\`\`\`
+1. Read .context/  →  2. Receive task  →  3. Implement  →  4. Update .context/
+\`\`\`
+`;
+export const tocketMd = (projectName) => `# Tocket Protocol Specification
+
+> How any AI agent should operate in **${projectName}**.
+
+This file is **agent-agnostic**. Whether you are Claude, Gemini, GPT, Cursor, Cline, Copilot, or any future AI — if you see this file, follow these rules.
+
+---
+
+## 1. Memory Bank
+
+Project context lives in \`.context/\`, not in chat history. **Read it before doing anything.**
+
+\`\`\`
+.context/
+  activeContext.md    <- Start here. Current focus, recent changes, open decisions.
+  systemPatterns.md   <- Architecture patterns, conventions, key decisions.
+  techContext.md      <- Tech stack, build tools, critical rules.
+  productContext.md   <- What the product is, who it's for, why it exists.
+  progress.md         <- What's done, what's next.
+\`\`\`
+
+### Rules
+
+- **Read before acting** — Always read \`activeContext.md\` and \`systemPatterns.md\` before your first action in a session.
+- **Write before leaving** — Update \`activeContext.md\` with what changed after completing significant work.
+- **Trust the files** — If \`.context/\` says the project uses ESM, it uses ESM. Don't second-guess documented decisions.
+- **Don't duplicate** — Context belongs in \`.context/\`, not scattered in code comments or chat summaries.
+
+---
+
+## 2. Triangulation
+
+Tocket separates **planning** from **implementation** across two agent roles:
+
+\`\`\`
+┌─────────────────┐          ┌─────────────────┐
+│    ARCHITECT     │          │    EXECUTOR      │
+│  (Planner)       │  payload │  (Implementer)   │
+│                  │─────────>│                  │
+│  Analyzes task   │          │  Receives plan   │
+│  Designs approach│          │  Writes code     │
+│  Generates XML   │          │  Runs tests      │
+│  Updates patterns│          │  Updates context  │
+└─────────────────┘          └─────────────────┘
+\`\`\`
+
+### Architect
+
+- Reads \`.context/\` to understand current state
+- Produces structured payloads (see Section 3) with clear tasks
+- Makes architectural decisions and records them in \`systemPatterns.md\`
+- **Does not write code** — only specs and constraints
+
+### Executor
+
+- Reads \`.context/\` and the Architect's payload
+- Implements tasks exactly as specified
+- Asks when the plan is unclear — does not improvise architecture
+- Updates \`activeContext.md\` and \`progress.md\` after completing work
+
+### Solo Mode
+
+Not every task needs triangulation. For simple, well-defined changes, a single agent can act as both Architect and Executor. The Memory Bank rules still apply.
+
+---
+
+## 3. Payloads
+
+A payload is the structured handoff from Architect to Executor.
+
+### Minimal Example
+
+\`\`\`xml
+<payload version="2.0">
+  <meta>
+    <intent>Goal in one line</intent>
+    <scope>Files affected</scope>
+    <priority>high | medium | low</priority>
+  </meta>
+  <tasks>
+    <task id="1" type="create | edit | delete">
+      <target>file/path</target>
+      <action>What to do</action>
+      <done>Definition of done</done>
+    </task>
+  </tasks>
+  <validate>
+    <check>How to verify success</check>
+  </validate>
+</payload>
+\`\`\`
+
+---
+
+## Quick Start
+
+1. Read this file (\`TOCKET.md\`)
+2. Read \`.context/activeContext.md\` for current state
+3. Read your role-specific config (\`CLAUDE.md\` or \`GEMINI.md\`)
+4. Proceed with your task, following the Memory Bank rules above
+`;

package/dist/tests/memory-bank.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/tests/memory-bank.test.js

@@ -0,0 +1,199 @@
+import { describe, it } from "node:test";
+import assert from "node:assert/strict";
+import { claudeMd, geminiMd, tocketMd, activeContextMd, systemPatternsMd, productContextMd, techContextMd, progressMd, cursorrulesMd, } from "../templates/memory-bank.js";
+describe("claudeMd", () => {
+    const output = claudeMd("TestProject", "A test project");
+    it("includes the project name in the title", () => {
+        assert.ok(output.includes("# CLAUDE.md - TestProject"));
+    });
+    it("includes the description as a blockquote", () => {
+        assert.ok(output.includes("> A test project"));
+    });
+    it("defines the Executor role", () => {
+        assert.ok(output.includes("**Executor**"));
+    });
+    it("references the Memory Bank files", () => {
+        assert.ok(output.includes(".context/activeContext.md"));
+        assert.ok(output.includes(".context/systemPatterns.md"));
+    });
+    it("handles empty description gracefully", () => {
+        const noDesc = claudeMd("Foo", "");
+        assert.ok(noDesc.includes("# CLAUDE.md - Foo"));
+        assert.ok(!noDesc.includes("> \n"));
+    });
+});
+describe("geminiMd", () => {
+    const output = geminiMd("TestProject", "A test project");
+    it("includes the project name in the title", () => {
+        assert.ok(output.includes("# GEMINI.md - TestProject"));
+    });
+    it("defines the Architect role", () => {
+        assert.ok(output.includes("**Architect**"));
+    });
+    it("references payload v2.0 format", () => {
+        assert.ok(output.includes('<payload version="2.0">'));
+    });
+    it("does not reference the deprecated mission-brief format", () => {
+        assert.ok(!output.includes("<mission-brief"));
+    });
+});
+describe("tocketMd", () => {
+    const output = tocketMd("TestProject");
+    it("includes the protocol title", () => {
+        assert.ok(output.includes("# Tocket Protocol Specification"));
+    });
+    it("includes the project name", () => {
+        assert.ok(output.includes("**TestProject**"));
+    });
+    it("declares agent-agnostic stance", () => {
+        assert.ok(output.includes("agent-agnostic"));
+    });
+    it("documents all 5 Memory Bank files", () => {
+        assert.ok(output.includes("activeContext.md"));
+        assert.ok(output.includes("systemPatterns.md"));
+        assert.ok(output.includes("techContext.md"));
+        assert.ok(output.includes("productContext.md"));
+        assert.ok(output.includes("progress.md"));
+    });
+    it("documents the Triangulation pattern", () => {
+        assert.ok(output.includes("ARCHITECT"));
+        assert.ok(output.includes("EXECUTOR"));
+    });
+    it("includes a payload example with v2.0", () => {
+        assert.ok(output.includes('<payload version="2.0">'));
+    });
+});
+describe("activeContextMd", () => {
+    const output = activeContextMd("TestProject");
+    it("includes the project name", () => {
+        assert.ok(output.includes("# Active Context - TestProject"));
+    });
+    it("has the required sections", () => {
+        assert.ok(output.includes("## Current Focus"));
+        assert.ok(output.includes("## Recent Changes"));
+        assert.ok(output.includes("## Open Decisions"));
+    });
+    it("includes a date in the recent changes table", () => {
+        assert.match(output, /\d{4}-\d{2}-\d{2}/);
+    });
+});
+describe("systemPatternsMd", () => {
+    const output = systemPatternsMd("TestProject");
+    it("includes the project name", () => {
+        assert.ok(output.includes("# System Patterns - TestProject"));
+    });
+    it("has the required sections", () => {
+        assert.ok(output.includes("## Tech Stack"));
+        assert.ok(output.includes("## Conventions"));
+        assert.ok(output.includes("## Key Decisions"));
+    });
+});
+describe("productContextMd", () => {
+    it("includes the project name and description", () => {
+        const output = productContextMd("TestProject", "A cool tool");
+        assert.ok(output.includes("# Product Context - TestProject"));
+        assert.ok(output.includes("A cool tool"));
+    });
+    it("shows placeholder when description is empty", () => {
+        const output = productContextMd("TestProject", "");
+        assert.ok(output.includes("_Describe your product here._"));
+    });
+    it("has the required sections", () => {
+        const output = productContextMd("TestProject", "desc");
+        assert.ok(output.includes("## Problem"));
+        assert.ok(output.includes("## Solution"));
+        assert.ok(output.includes("## Target Users"));
+    });
+});
+describe("techContextMd", () => {
+    it("includes the project name", () => {
+        const output = techContextMd("TestProject");
+        assert.ok(output.includes("# Tech Context - TestProject"));
+    });
+    it("has a stack table", () => {
+        const output = techContextMd("TestProject");
+        assert.ok(output.includes("| Language |"));
+        assert.ok(output.includes("| Runtime |"));
+    });
+    it("includes project structure with project name", () => {
+        const output = techContextMd("TestProject");
+        assert.ok(output.includes("TestProject/"));
+    });
+    it("renders empty rows when no stack provided", () => {
+        const output = techContextMd("TestProject");
+        // Should have empty cells (no "Auto-detected")
+        assert.ok(!output.includes("Auto-detected"));
+    });
+    it("renders detected stack when StackInfo is provided", () => {
+        const stack = {
+            language: "TypeScript",
+            runtime: "Node.js",
+            build: "Vite",
+            framework: "React",
+            extras: ["tailwindcss", "prisma"],
+        };
+        const output = techContextMd("TestProject", stack);
+        assert.ok(output.includes("TypeScript"));
+        assert.ok(output.includes("Node.js"));
+        assert.ok(output.includes("Vite"));
+        assert.ok(output.includes("React"));
+        assert.ok(output.includes("Auto-detected by Tocket"));
+    });
+    it("renders notable dependencies when extras are present", () => {
+        const stack = {
+            language: "TypeScript",
+            runtime: "Node.js",
+            build: "tsc",
+            framework: "",
+            extras: ["tailwindcss", "zod"],
+        };
+        const output = techContextMd("TestProject", stack);
+        assert.ok(output.includes("### Notable Dependencies"));
+        assert.ok(output.includes("`tailwindcss`"));
+        assert.ok(output.includes("`zod`"));
+    });
+    it("omits notable dependencies section when extras are empty", () => {
+        const stack = {
+            language: "TypeScript",
+            runtime: "Node.js",
+            build: "tsc",
+            framework: "",
+            extras: [],
+        };
+        const output = techContextMd("TestProject", stack);
+        assert.ok(!output.includes("### Notable Dependencies"));
+    });
+});
+describe("progressMd", () => {
+    const output = progressMd("TestProject");
+    it("includes the project name", () => {
+        assert.ok(output.includes("# Progress Log - TestProject"));
+    });
+    it("has an initialization milestone marked complete", () => {
+        assert.ok(output.includes("**Status**: Complete"));
+    });
+    it("has a Next Up section", () => {
+        assert.ok(output.includes("## Next Up"));
+    });
+});
+describe("cursorrulesMd", () => {
+    const output = cursorrulesMd("TestProject", "A cool CLI tool");
+    it("includes the project name", () => {
+        assert.ok(output.includes("# .cursorrules - TestProject"));
+    });
+    it("includes the description as a blockquote", () => {
+        assert.ok(output.includes("> A cool CLI tool"));
+    });
+    it("defines the Executor role", () => {
+        assert.ok(output.includes("**Executor**"));
+    });
+    it("references Memory Bank files", () => {
+        assert.ok(output.includes(".context/activeContext.md"));
+        assert.ok(output.includes(".context/systemPatterns.md"));
+    });
+    it("handles empty description gracefully", () => {
+        const noDesc = cursorrulesMd("Foo", "");
+        assert.ok(noDesc.includes("# .cursorrules - Foo"));
+        assert.ok(!noDesc.includes("> \n"));
+    });
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pedrocivita/tocket",
-  "version": "1.0.0",
+  "version": "1.2.0",
   "description": "The Context Engineering Framework for Multi-Agent Workspaces",
   "type": "module",
   "main": "dist/index.js",
@@ -14,7 +14,7 @@
     "build": "tsc",
     "start": "node dist/index.js",
     "prepublishOnly": "npm run build",
-    "test": "echo \"Error: no test specified\" && exit 1"
+    "test": "npm run build && node --test dist/tests/*.test.js"
   },
   "repository": {
     "type": "git",