@pedrocivita/tocket 2.0.0 → 2.2.0

package/README.md

@@ -1,132 +1,193 @@
-![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**
-
-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.
-
-Tocket fixes this with two primitives:
-
-- **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.
-
-## 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
-
-The protocol is just files. You can adopt it manually:
-
-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
-# Interactive dashboard — guided entry point
-npx @pedrocivita/tocket
-
-# Scaffold a new workspace (creates .context/, TOCKET.md, CLAUDE.md, GEMINI.md)
-npx @pedrocivita/tocket init
-
-# Generate a payload XML with smart git integration
-npx @pedrocivita/tocket generate
-
-# Sync session progress into Memory Bank
-npx @pedrocivita/tocket sync
-```
-
-## Commands
-
-| Command           | What it does                                                         |
-| ----------------- | -------------------------------------------------------------------- |
-| `tocket`          | Interactive dashboard with guided menu                               |
-| `tocket init`     | Scaffolds `.context/`, `TOCKET.md`, `CLAUDE.md`, `GEMINI.md`         |
-| `tocket generate` | Smart payload builder — auto-fills scope from git, multi-task support |
-| `tocket sync`     | Appends session summary + git log to `.context/progress.md`          |
-| `tocket validate` | Checks if the current directory has a valid Tocket Memory Bank       |
-| `tocket config`   | Manage global settings (`~/.tocketrc.json`)                          |
-
-## Configuration
-
-Set global defaults so you don't repeat yourself:
-
-```bash
-# Interactive setup
-tocket config
-
-# Or use flags (CI-friendly)
-tocket config --author "Your Name" --priority medium --skills "core,lsp"
-
-# View current config
-tocket config --show
-```
-
-Config is stored at `~/.tocketrc.json` and pre-fills author, priority, and skills in all commands.
-
-## 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
+![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**
+
+AI agents forget everything between sessions. When multiple agents work on the same codebase, they re-read files, duplicate work, and make conflicting decisions. Tocket fixes this with **shared context files that any agent can read** — no vendor lock-in, no special integrations.
+
+<p align="center">
+  <img src="docs/assets/tocket-dashboard.png" alt="Tocket CLI Dashboard" width="700" />
+</p>
+
+## The idea in 30 seconds
+
+Tocket is a file convention. It adds a `.context/` directory to your repo with markdown files that describe your project's current state, architecture, and progress. Any AI agent that can read files — Claude, Gemini, GPT, Cursor, Copilot — can pick up where the last session left off.
+
+```
+your-project/
+  .context/
+    activeContext.md      # What's happening right now
+    systemPatterns.md     # How the codebase is organized
+    techContext.md        # Stack and build tools
+    productContext.md     # What the product is and why
+    progress.md           # What's done, what's next
+  TOCKET.md               # Protocol rules (for any AI)
+  CLAUDE.md               # Executor agent config
+  GEMINI.md               # Architect agent config
+```
+
+All files are plain markdown, committed to git, and readable by any tool.
+
+## You don't need the CLI
+
+The protocol is just files. You can adopt it manually:
+
+1. Create a `.context/` directory with `activeContext.md` and `systemPatterns.md`
+2. Add a [`TOCKET.md`](TOCKET.md) to your repo root
+3. Tell your agents to read `.context/` before acting
+
+The CLI automates the scaffolding, provides smart defaults, and adds quality-of-life tooling around the protocol.
+
+## Quick Start
+
+```bash
+# Scaffold a new workspace (creates .context/, TOCKET.md, CLAUDE.md, GEMINI.md)
+npx @pedrocivita/tocket init
+
+# Or just the essentials (3 files)
+npx @pedrocivita/tocket init --minimal
+
+# Or open the interactive dashboard
+npx @pedrocivita/tocket
+```
+
+That's it. Your repo now has a Memory Bank. Every AI session starts by reading `.context/activeContext.md`.
+
+### Safe testing — use a branch
+
+Tocket writes files to your repo, but you can try it risk-free on a branch:
+
+```bash
+git checkout -b test/tocket-setup
+npx @pedrocivita/tocket init
+git add .context/ TOCKET.md CLAUDE.md GEMINI.md .cursorrules
+git commit -m "chore: scaffold Tocket workspace"
+
+# Try it out — run some AI sessions, see if you like it
+# Don't like it? Clean up:
+npx @pedrocivita/tocket eject     # removes all Tocket files
+# Or just delete the branch:
+git checkout main && git branch -D test/tocket-setup
+```
+
+See the [Developer Guide](docs/DEVELOPERS_GUIDE.md) for detailed safe-testing workflows.
+
+## Commands
+
+| Command | What it does |
+| --- | --- |
+| `tocket` | Interactive dashboard with guided menu |
+| `tocket init` | Scaffold `.context/`, `TOCKET.md`, and agent configs (auto-detects your stack) |
+| `tocket generate` | Build structured payload XML (auto-fills scope from git) |
+| `tocket sync` | Append session summary + git log to `.context/progress.md` |
+| `tocket validate` | Check if the workspace has a valid Memory Bank |
+| `tocket focus` | Update the Current Focus in `activeContext.md` |
+| `tocket status` | Quick overview: workspace health, branch, focus, agents |
+| `tocket doctor` | Deep workspace diagnostics (content health, git tracking, staleness) |
+| `tocket lint` | Audit `.context/` content quality and suggest improvements |
+| `tocket config` | Manage global settings (`~/.tocketrc.json`) |
+| `tocket eject` | Remove all Tocket files (with confirmation) |
+
+### CI-friendly flags
+
+Every interactive command has flags for non-interactive use:
+
+```bash
+# Minimal init (3 files instead of 9)
+tocket init --minimal --name myproject --description "My app" --force
+
+# Sync without prompt
+tocket sync --summary "Fixed auth bug and added tests"
+
+# Generate to stdout or file instead of clipboard
+tocket generate --to stdout
+tocket generate --to payload.xml
+```
+
+## How it works
+
+### Memory Bank
+
+The `.context/` directory is the project's shared memory. Agents read it before acting and update it after completing work. Context lives in files, not in chat history.
+
+| File | Purpose | Updated |
+| --- | --- | --- |
+| `activeContext.md` | Current focus, recent changes, open decisions | Every session |
+| `systemPatterns.md` | Architecture patterns and conventions | When patterns change |
+| `techContext.md` | Stack, build tools, critical rules | When stack changes |
+| `productContext.md` | What the product is and why | Rarely |
+| `progress.md` | Milestones and completed work | Per milestone |
+
+### Triangulation
+
+For complex tasks, Tocket separates planning from implementation:
+
+```
+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 XML is the contract between them. For simple tasks, a single agent can fill both roles.
+
+## 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
+- Open-source maintainers who want contributors' AI agents to follow project conventions
+
+## How is Tocket different?
+
+| 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 |
+
+## Configuration
+
+Set global defaults so you don't repeat yourself:
+
+```bash
+# Interactive setup
+tocket config
+
+# Or use flags (CI-friendly)
+tocket config --author "Your Name" --priority medium --skills "core,lsp"
+
+# View current config
+tocket config --show
+```
+
+Config is stored at `~/.tocketrc.json` and pre-fills author, priority, and skills in all commands.
+
+## Documentation
+
+| Guide | Description |
+| --- | --- |
+| [Getting Started](docs/GETTING_STARTED.md) | Set up your first Tocket workspace in 5 minutes |
+| [Developer Guide](docs/DEVELOPERS_GUIDE.md) | How to run the Tocket protocol safely in any project |
+| [Tocket Rules](docs/TOCKET_RULES.md) | Complete reference for all protocol rules |
+| [Protocol Spec](TOCKET.md) | The agent-agnostic protocol specification |
+
+## 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/dashboard.js

@@ -44,7 +44,12 @@ export async function showDashboard(program) {
             { value: "generate", name: "Generate payload" },
             { value: "sync", name: "Sync progress" },
             { value: "validate", name: "Validate workspace" },
+            { value: "focus", name: "Update focus" },
+            { value: "status", name: "Workspace status" },
+            { value: "doctor", name: "Run diagnostics" },
+            { value: "lint", name: "Lint context quality" },
             { value: "config", name: "Configure settings" },
+            { value: "eject", name: "Eject workspace" },
             { value: "exit", name: "Exit" },
         ]
         : [

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

@@ -0,0 +1,9 @@
+import type { Command } from "commander";
+export interface DiagResult {
+    icon: string;
+    message: string;
+}
+export declare function checkContentHealth(basePath: string): DiagResult[];
+export declare function checkGitTracking(cwd: string): DiagResult[];
+export declare function checkStaleness(basePath: string): DiagResult | null;
+export declare function registerDoctorCommand(program: Command): void;

package/dist/commands/doctor.cmd.js

@@ -0,0 +1,191 @@
+import { existsSync, readFileSync, statSync } from "node:fs";
+import { join } from "node:path";
+import { execSync } from "node:child_process";
+import { success as themePass, warn as themeWarn, error as themeFail, heading, dim } from "../utils/theme.js";
+import { isGitRepo } from "../utils/git.js";
+const PASS = themePass("");
+const WARN = themeWarn("");
+const FAIL = themeFail("");
+export function checkContentHealth(basePath) {
+    const results = [];
+    // activeContext.md: non-empty Current Focus
+    const acPath = join(basePath, ".context", "activeContext.md");
+    if (existsSync(acPath)) {
+        const content = readFileSync(acPath, "utf-8");
+        const focusMatch = content.match(/## Current Focus\s*\n+([\s\S]*?)(?=\n##|\n*$)/);
+        const focusBody = focusMatch?.[1]?.trim() ?? "";
+        if (!focusBody || focusBody.startsWith("_") || focusBody.includes("No active tasks")) {
+            results.push({ icon: WARN, message: "activeContext.md has no meaningful Current Focus" });
+        }
+        else {
+            results.push({ icon: PASS, message: "activeContext.md has an active focus" });
+        }
+    }
+    // systemPatterns.md: has at least one convention
+    const spPath = join(basePath, ".context", "systemPatterns.md");
+    if (existsSync(spPath)) {
+        const content = readFileSync(spPath, "utf-8");
+        const hasConvention = content.includes("- ") || content.includes("| ");
+        if (hasConvention) {
+            results.push({ icon: PASS, message: "systemPatterns.md has documented conventions" });
+        }
+        else {
+            results.push({ icon: WARN, message: "systemPatterns.md has no conventions documented" });
+        }
+    }
+    // TOCKET.md: contains payload or version keyword
+    const tocketPath = join(basePath, "TOCKET.md");
+    if (existsSync(tocketPath)) {
+        const content = readFileSync(tocketPath, "utf-8");
+        if (content.includes("payload") || content.includes("version")) {
+            results.push({ icon: PASS, message: "TOCKET.md contains protocol keywords" });
+        }
+        else {
+            results.push({ icon: WARN, message: "TOCKET.md may not be a valid protocol spec" });
+        }
+    }
+    // Agent configs reference .context/
+    const agentFiles = ["CLAUDE.md", "GEMINI.md"];
+    for (const af of agentFiles) {
+        const afPath = join(basePath, af);
+        if (existsSync(afPath)) {
+            const content = readFileSync(afPath, "utf-8");
+            if (content.includes(".context/") || content.includes(".context\\")) {
+                results.push({ icon: PASS, message: `${af} references .context/` });
+            }
+            else {
+                results.push({ icon: WARN, message: `${af} does not reference .context/` });
+            }
+        }
+    }
+    return results;
+}
+export function checkGitTracking(cwd) {
+    const results = [];
+    if (!isGitRepo(cwd)) {
+        results.push({ icon: WARN, message: "Not a git repository" });
+        return results;
+    }
+    // Check if .context/ is in .gitignore
+    try {
+        const output = execSync("git check-ignore .context/", {
+            cwd,
+            encoding: "utf-8",
+        }).trim();
+        if (output) {
+            results.push({ icon: FAIL, message: ".context/ is in .gitignore (should be tracked)" });
+        }
+    }
+    catch {
+        // exit code 1 = not ignored (good)
+        results.push({ icon: PASS, message: ".context/ is not gitignored" });
+    }
+    // Check for uncommitted .context/ changes
+    try {
+        const output = execSync("git status --porcelain .context/", {
+            cwd,
+            encoding: "utf-8",
+        }).trim();
+        if (output) {
+            const count = output.split("\n").length;
+            results.push({ icon: WARN, message: `${count} uncommitted change(s) in .context/` });
+        }
+        else {
+            results.push({ icon: PASS, message: ".context/ files are committed" });
+        }
+    }
+    catch {
+        // git error — skip
+    }
+    return results;
+}
+export function checkStaleness(basePath) {
+    const acPath = join(basePath, ".context", "activeContext.md");
+    if (!existsSync(acPath))
+        return null;
+    const stats = statSync(acPath);
+    const daysSinceModified = Math.floor((Date.now() - stats.mtimeMs) / (1000 * 60 * 60 * 24));
+    if (daysSinceModified > 7) {
+        return {
+            icon: WARN,
+            message: `activeContext.md last modified ${daysSinceModified} days ago (may be stale)`,
+        };
+    }
+    return null;
+}
+export function registerDoctorCommand(program) {
+    program
+        .command("doctor")
+        .description("Deep diagnostic of a Tocket workspace")
+        .action(() => {
+        const cwd = process.cwd();
+        const results = [];
+        let passCount = 0;
+        let warnCount = 0;
+        let failCount = 0;
+        console.log(heading("\nTocket Doctor\n"));
+        // 1. File existence (same as validate)
+        const contextDir = join(cwd, ".context");
+        if (!existsSync(contextDir)) {
+            results.push({ icon: FAIL, message: ".context/ directory missing" });
+        }
+        else {
+            results.push({ icon: PASS, message: ".context/ directory found" });
+            const requiredFiles = ["activeContext.md", "systemPatterns.md"];
+            const optionalFiles = ["techContext.md", "productContext.md", "progress.md"];
+            for (const f of requiredFiles) {
+                if (existsSync(join(contextDir, f))) {
+                    results.push({ icon: PASS, message: `.context/${f} found` });
+                }
+                else {
+                    results.push({ icon: FAIL, message: `.context/${f} missing (required)` });
+                }
+            }
+            for (const f of optionalFiles) {
+                if (existsSync(join(contextDir, f))) {
+                    results.push({ icon: PASS, message: `.context/${f} found` });
+                }
+                else {
+                    results.push({ icon: WARN, message: `.context/${f} missing (optional)` });
+                }
+            }
+        }
+        if (existsSync(join(cwd, "TOCKET.md"))) {
+            results.push({ icon: PASS, message: "TOCKET.md found" });
+        }
+        else {
+            results.push({ icon: FAIL, message: "TOCKET.md missing (required)" });
+        }
+        // 2. Content health
+        results.push(...checkContentHealth(cwd));
+        // 3. Staleness
+        const stale = checkStaleness(cwd);
+        if (stale)
+            results.push(stale);
+        // 4. Git tracking
+        results.push(...checkGitTracking(cwd));
+        // Print results
+        for (const r of results) {
+            console.log(`  ${r.icon} ${r.message}`);
+            if (r.icon === PASS)
+                passCount++;
+            else if (r.icon === WARN)
+                warnCount++;
+            else
+                failCount++;
+        }
+        console.log("");
+        console.log(dim(`  ${passCount} passed, ${warnCount} warnings, ${failCount} failures`));
+        console.log("");
+        if (failCount > 0) {
+            console.log(themeFail("Workspace has issues.") + " Run tocket init to scaffold missing files.");
+            process.exitCode = 1;
+        }
+        else if (warnCount > 0) {
+            console.log(themeWarn("Workspace is functional but has warnings."));
+        }
+        else {
+            console.log(themePass("Workspace is in great shape."));
+        }
+    });
+}

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

@@ -0,0 +1,6 @@
+import type { Command } from "commander";
+/** Files created by `tocket init` that eject should remove. */
+export declare const EJECT_FILES: readonly ["TOCKET.md", "CLAUDE.md", "GEMINI.md", ".cursorrules"];
+/** Directories created by `tocket init` that eject should remove. */
+export declare const EJECT_DIRS: readonly [".context"];
+export declare function registerEjectCommand(program: Command): void;

package/dist/commands/eject.cmd.js

@@ -0,0 +1,65 @@
+import { confirm } from "@inquirer/prompts";
+import { existsSync } from "node:fs";
+import { rm } from "node:fs/promises";
+import { join } from "node:path";
+import { success, warn, info, dim } from "../utils/theme.js";
+/** Files created by `tocket init` that eject should remove. */
+export const EJECT_FILES = [
+    "TOCKET.md",
+    "CLAUDE.md",
+    "GEMINI.md",
+    ".cursorrules",
+];
+/** Directories created by `tocket init` that eject should remove. */
+export const EJECT_DIRS = [".context"];
+export function registerEjectCommand(program) {
+    program
+        .command("eject")
+        .description("Remove all Tocket files from the current workspace")
+        .option("-f, --force", "Skip confirmation prompt")
+        .action(async (options) => {
+        const cwd = process.cwd();
+        const contextDir = join(cwd, ".context");
+        if (!existsSync(contextDir)) {
+            console.log(warn("No Tocket workspace found in this directory."));
+            return;
+        }
+        if (!options.force) {
+            const ok = await confirm({
+                message: "This will permanently remove .context/, CLAUDE.md, GEMINI.md, TOCKET.md, and .cursorrules. Continue?",
+                default: false,
+            });
+            if (!ok) {
+                console.log(dim("\n  Cancelled.\n"));
+                return;
+            }
+        }
+        let removedCount = 0;
+        for (const dir of EJECT_DIRS) {
+            const fullPath = join(cwd, dir);
+            if (existsSync(fullPath)) {
+                await rm(fullPath, { recursive: true, force: true });
+                console.log(info(`Removed ${dir}/`));
+                removedCount++;
+            }
+        }
+        for (const file of EJECT_FILES) {
+            const fullPath = join(cwd, file);
+            if (existsSync(fullPath)) {
+                await rm(fullPath, { force: true });
+                console.log(info(`Removed ${file}`));
+                removedCount++;
+            }
+        }
+        if (removedCount === 0) {
+            console.log(warn("Nothing to remove."));
+        }
+        else {
+            console.log("\n" +
+                success("Tocket workspace ejected.") +
+                " " +
+                dim("Global config (~/.tocketrc.json) was not touched.") +
+                "\n");
+        }
+    });
+}

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

@@ -0,0 +1,7 @@
+import type { Command } from "commander";
+/**
+ * Replaces the content under ## Current Focus with the new message.
+ * Exported for testing.
+ */
+export declare function replaceFocusSection(content: string, newFocus: string): string;
+export declare function registerFocusCommand(program: Command): void;