monomind 2.5.1 → 2.5.3

package/packages/@monomind/cli/.claude/skills/monodesign/scripts/pin.mjs

@@ -0,0 +1,221 @@
+#!/usr/bin/env node
+/**
+ * Pin/unpin sub-commands as standalone skill shortcuts.
+ *
+ * Usage:
+ *   node <scripts_path>/pin.mjs pin <command>
+ *   node <scripts_path>/pin.mjs unpin <command>
+ *
+ * `pin audit` creates a lightweight audit skill that redirects to Monodesign's audit workflow.
+ * `unpin audit` removes that shortcut.
+ *
+ * The script discovers harness directories (.claude/skills, .cursor/skills, etc.)
+ * in the project root and creates/removes the pin in all of them.
+ */
+
+import { existsSync, readFileSync, writeFileSync, mkdirSync, rmSync, readdirSync } from 'node:fs';
+import { basename, join, resolve, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+
+// All known harness directories
+const HARNESS_DIRS = [
+  '.claude', '.cursor', '.gemini', '.codex', '.agents',
+  '.trae', '.trae-cn', '.pi', '.opencode', '.kiro', '.rovodev',
+];
+
+const CODEX_HARNESSES = new Set(['.codex', '.agents']);
+
+// Valid sub-command names
+const VALID_COMMANDS = [
+  'craft', 'init', 'extract', 'document', 'shape',
+  'critique', 'audit',
+  'polish', 'bolder', 'quieter', 'distill', 'harden', 'onboard', 'live',
+  'animate', 'colorize', 'typeset', 'layout', 'delight', 'overdrive',
+  'clarify', 'adapt', 'optimize',
+];
+
+// Marker to identify pinned skills (so unpin doesn't delete user skills)
+const PIN_MARKER = '<!-- monodesign-pinned-skill -->';
+
+/**
+ * Walk up from startDir to find a project root.
+ */
+function findProjectRoot(startDir = process.cwd()) {
+  let dir = resolve(startDir);
+  while (dir !== '/') {
+    if (
+      existsSync(join(dir, 'package.json')) ||
+      existsSync(join(dir, '.git')) ||
+      existsSync(join(dir, 'skills-lock.json'))
+    ) {
+      return dir;
+    }
+    const parent = resolve(dir, '..');
+    if (parent === dir) break;
+    dir = parent;
+  }
+  return resolve(startDir);
+}
+
+/**
+ * Find harness skill directories that have an monodesign skill installed.
+ */
+function findHarnessDirs(projectRoot) {
+  const dirs = [];
+  for (const harness of HARNESS_DIRS) {
+    const skillsDir = join(projectRoot, harness, 'skills');
+    // Only pin in harness dirs that already have monodesign installed
+    const monodesignDir = join(skillsDir, 'monodesign');
+    if (existsSync(monodesignDir) || existsSync(join(skillsDir, 'i-monodesign'))) {
+      dirs.push(skillsDir);
+    }
+  }
+  return dirs;
+}
+
+/**
+ * Load command metadata (descriptions for pinned skills).
+ */
+function loadCommandMetadata() {
+  const metadataPath = join(__dirname, 'command-metadata.json');
+  if (existsSync(metadataPath)) {
+    return JSON.parse(readFileSync(metadataPath, 'utf-8'));
+  }
+  return {};
+}
+
+/**
+ * Generate a pinned skill's SKILL.md content.
+ */
+function commandPrefixForSkillsDir(skillsDir) {
+  return CODEX_HARNESSES.has(basename(dirname(skillsDir))) ? '$' : '/';
+}
+
+function generatePinnedSkill(command, metadata, commandPrefix) {
+  const desc = metadata[command]?.description || `Shortcut for ${commandPrefix}monodesign ${command}.`;
+  const hint = metadata[command]?.argumentHint || '[target]';
+
+  return `---
+name: ${command}
+description: "${desc}"
+argument-hint: "${hint}"
+user-invocable: true
+---
+
+${PIN_MARKER}
+
+This is a pinned shortcut for \`${commandPrefix}monodesign ${command}\`.
+
+Invoke ${commandPrefix}monodesign ${command}, passing along any arguments provided here, and follow its instructions.
+`;
+}
+
+/**
+ * Pin a command: create shortcut skill in all harness dirs.
+ */
+function pin(command, projectRoot) {
+  const metadata = loadCommandMetadata();
+  const harnessDirs = findHarnessDirs(projectRoot);
+
+  if (harnessDirs.length === 0) {
+    console.log('No harness directories with monodesign installed found.');
+    return false;
+  }
+
+  let created = 0;
+
+  for (const skillsDir of harnessDirs) {
+    const commandPrefix = commandPrefixForSkillsDir(skillsDir);
+    const content = generatePinnedSkill(command, metadata, commandPrefix);
+    // Check if skill already exists (and isn't a pin)
+    const skillDir = join(skillsDir, command);
+    if (existsSync(skillDir)) {
+      const existingMd = join(skillDir, 'SKILL.md');
+      if (existsSync(existingMd)) {
+        const existing = readFileSync(existingMd, 'utf-8');
+        if (!existing.includes(PIN_MARKER)) {
+          console.log(`  SKIP: ${skillDir} (non-pinned skill already exists)`);
+          continue;
+        }
+      }
+    }
+
+    mkdirSync(skillDir, { recursive: true });
+    writeFileSync(join(skillDir, 'SKILL.md'), content, 'utf-8');
+    console.log(`  + ${skillDir}`);
+    created++;
+  }
+
+  if (created > 0) {
+    console.log(`\nPinned '${command}' as a standalone shortcut in ${created} location(s).`);
+    console.log('Use the pinned command directly in each harness.');
+  }
+
+  return created > 0;
+}
+
+/**
+ * Unpin a command: remove shortcut skill from all harness dirs.
+ */
+function unpin(command, projectRoot) {
+  const harnessDirs = findHarnessDirs(projectRoot);
+  let removed = 0;
+
+  for (const skillsDir of harnessDirs) {
+    const skillDir = join(skillsDir, command);
+    if (!existsSync(skillDir)) continue;
+
+    const skillMd = join(skillDir, 'SKILL.md');
+    if (!existsSync(skillMd)) continue;
+
+    // Safety: only remove if it's a pinned skill
+    const content = readFileSync(skillMd, 'utf-8');
+    if (!content.includes(PIN_MARKER)) {
+      console.log(`  SKIP: ${skillDir} (not a pinned skill)`);
+      continue;
+    }
+
+    rmSync(skillDir, { recursive: true, force: true });
+    console.log(`  - ${skillDir}`);
+    removed++;
+  }
+
+  if (removed > 0) {
+    console.log(`\nUnpinned '${command}' from ${removed} location(s).`);
+    console.log(`Use Monodesign's '${command}' workflow directly to access it.`);
+  } else {
+    console.log(`No pinned '${command}' shortcut found.`);
+  }
+
+  return removed > 0;
+}
+
+// --- CLI ---
+const [,, action, command] = process.argv;
+
+if (!action || !command) {
+  console.log('Usage: node pin.mjs <pin|unpin> <command>');
+  console.log(`\nAvailable commands: ${VALID_COMMANDS.join(', ')}`);
+  process.exit(1);
+}
+
+if (action !== 'pin' && action !== 'unpin') {
+  console.error(`Unknown action: ${action}. Use 'pin' or 'unpin'.`);
+  process.exit(1);
+}
+
+if (!VALID_COMMANDS.includes(command)) {
+  console.error(`Unknown command: ${command}`);
+  console.error(`Available commands: ${VALID_COMMANDS.join(', ')}`);
+  process.exit(1);
+}
+
+const root = findProjectRoot();
+
+if (action === 'pin') {
+  pin(command, root);
+} else {
+  unpin(command, root);
+}

package/packages/@monomind/cli/.claude/skills/monodesign/teach.md

@@ -1,69 +1,18 @@
 ---
 name: monodesign-teach
-description: Create or update PRODUCT.md — extract product context, users, brand voice, and design principles from the codebase, existing files, and conversation to anchor all future monodesign work.
+description: Alias of /monodesign init — set up a project for monodesign by producing PRODUCT.md (strategic context), optionally DESIGN.md (visual system), and pre-configuring live mode.
 type: design-sub-command
 argument-hint: "[project path or description]"
 user-invocable: true
 ---
 
-# Monodesign: Teach
+# Monodesign: Teach (alias of Init)
 
-Create or update `PRODUCT.md` — the required context anchor for all `/monodesign` sub-commands.
+`teach` is the historical name for the setup command and remains fully supported; it is an alias of `init`. Both invocations behave identically.
 
-`PRODUCT.md` is not a design document — it's the product context document. It answers: who uses this, what is it for, what is the brand personality, and what design anti-references should be avoided.
+Follow `commands/init.md` and the authoritative flow in `reference/init.md` from the monodesign skill directory: one codebase crawl plus a short strategic interview produces **PRODUCT.md** (register, users, purpose, brand personality, anti-references, design principles), offers **DESIGN.md** via `/monodesign document`, and pre-configures `.monodesign/live/config.json` for `/monodesign live`.
 
-## When to Run
+Notes preserved from the teach era:
 
-Run `/monodesign teach` when:
-- Starting work on a new project with no `PRODUCT.md`
-- The existing `PRODUCT.md` is empty, placeholder (<200 chars), or has `[TODO]` markers
-- The product has significantly evolved and the `PRODUCT.md` is stale
-
-## Discovery Protocol
-
-**Step 1: Gather existing signals**
-
-Read the following files if they exist:
-- `README.md` — what is this product?
-- `package.json` — name, description, keywords
-- Any landing page copy (`index.html`, `src/pages/index.astro`, etc.)
-- Existing `PRODUCT.md` (to assess completeness)
-
-If a description or tagline exists, extract: target user, core value proposition, brand personality signals.
-
-**Step 2: Ask for what's missing**
-
-Ask the user 3–5 targeted questions based on what couldn't be inferred:
-- Who specifically uses this? (Role, context, skill level)
-- What's the one thing this does better than alternatives?
-- Three words that describe the brand personality
-- What design style do you want to AVOID? (anti-references)
-- Is this a marketing surface, product UI, or both?
-
-**Step 3: Write PRODUCT.md**
-
-```markdown
-# Product
-
-## Register
-[brand | product | both]
-
-## Users
-[Specific description of who uses this — not "developers", but "senior engineers at mid-size SaaS companies who need to..."]
-
-## Product Purpose
-[What this does and why it matters to those users. One paragraph.]
-
-## Brand Personality
-[3 words + a description of the tone. Direct, specific, no hedging.]
-
-## Anti-references
-[Specific things this product should NOT look like. Brand names, aesthetics, clichés to avoid.]
-
-## Design Principles
-[3–5 opinionated principles that guide all design decisions.]
-```
-
-## After Writing
-
-Confirm with the user that the PRODUCT.md is accurate before continuing to any design work. The PRODUCT.md is the foundation — if it's wrong, everything built on it is built on the wrong foundation.
+- A legacy `.monodesign.md` at the project root is auto-renamed to `PRODUCT.md` by the context loader; mention this once and merge into that content rather than starting fresh.
+- If teach was invoked as a setup blocker by another monodesign command, complete the init flow, then resume the original task with the fresh context.

package/packages/@monomind/cli/README.md

@@ -365,7 +365,7 @@ Everything runs from inside Claude Code via slash commands. Here's the highlight
 graph TD
     CC["Claude Code"]
     MCP["MCP Server\nmonomind mcp start"]
-    D["Background Workers\n(@monomind/hooks, in-process)"]
+    D["Background Workers\n(@monoes/hooks, in-process)"]
     ORG["OrgDaemon\nmonomind org run\nreal SDK sessions"]
 
     CC <-->|"MCP tools: monograph, memory"| MCP

package/packages/@monomind/cli/dist/src/commands/design-detect.d.ts

@@ -1,6 +1,6 @@
 /**
  * CLI Design Detect Command
- * Thin wrapper around impeccable's design anti-pattern detector
+ * Thin wrapper around the bundled @monoes/monodesign anti-pattern detector
  *
  * github.com/monoes/monomind
  */
@@ -16,6 +16,12 @@ export interface DesignDetectResult {
     patterns: DesignAntiPattern[];
     count: number;
 }
+/**
+ * Resolve the bundled monodesign CLI entry (cli/bin/cli.js) from the
+ * @monoes/monodesign package. Falls back to the monorepo sibling layout when
+ * running from a source checkout without installed workspace links.
+ */
+export declare function resolveMonodesignCli(): string | null;
 export declare const designCommand: Command;
 export default designCommand;
 //# sourceMappingURL=design-detect.d.ts.map

package/packages/@monomind/cli/dist/src/commands/design-detect.js

@@ -1,39 +1,52 @@
 /**
  * CLI Design Detect Command
- * Thin wrapper around impeccable's design anti-pattern detector
+ * Thin wrapper around the bundled @monoes/monodesign anti-pattern detector
  *
  * github.com/monoes/monomind
  */
 import { output } from '../output.js';
-import { spawn, execFile } from 'child_process';
-import { promisify } from 'util';
+import { spawn } from 'child_process';
+import { createRequire } from 'module';
+import { dirname, join } from 'path';
+import { existsSync } from 'fs';
+import { fileURLToPath } from 'url';
 import { paletteSubcommand } from './design-palette.js';
-const execFileAsync = promisify(execFile);
 // ─── Helpers ─────────────────────────────────────────────────────────────────
-async function isImpeccableAvailable() {
+/**
+ * Resolve the bundled monodesign CLI entry (cli/bin/cli.js) from the
+ * @monoes/monodesign package. Falls back to the monorepo sibling layout when
+ * running from a source checkout without installed workspace links.
+ */
+export function resolveMonodesignCli() {
+    // 1. Normal resolution through the package's "./engine" export.
     try {
-        await execFileAsync('npx', ['--no-install', 'impeccable', '--version'], { timeout: 5000 });
-        return true;
+        const require = createRequire(import.meta.url);
+        const enginePath = require.resolve('@monoes/monodesign/engine');
+        const binPath = join(dirname(enginePath), '..', 'bin', 'cli.js');
+        if (existsSync(binPath))
+            return binPath;
     }
     catch {
-        // Try checking via which
-        try {
-            await execFileAsync('which', ['impeccable'], { timeout: 3000 });
-            return true;
-        }
-        catch {
-            return false;
-        }
+        // fall through to monorepo-relative lookup
+    }
+    // 2. Monorepo layout: packages/@monomind/cli/{src|dist/src}/commands/ → packages/@monoes/monodesign
+    const here = dirname(fileURLToPath(import.meta.url));
+    for (const toCliRoot of ['../..', '../../..']) {
+        // <cli root>/../../@monoes/monodesign = packages/@monoes/monodesign
+        const candidate = join(here, toCliRoot, '..', '..', '@monoes', 'monodesign', 'cli', 'bin', 'cli.js');
+        if (existsSync(candidate))
+            return candidate;
     }
+    return null;
 }
-function runImpeccable(args) {
+function runMonodesign(cliPath, args) {
     return new Promise((resolve) => {
-        const child = spawn('npx', ['impeccable', 'detect', ...args], {
+        const child = spawn(process.execPath, [cliPath, ...args], {
             stdio: 'inherit',
             shell: false,
         });
         child.on('error', (err) => {
-            output.printError(`Failed to run impeccable: ${err.message}`);
+            output.printError(`Failed to run the monodesign detector: ${err.message}`);
             resolve(1);
         });
         child.on('close', (code) => {
@@ -41,10 +54,18 @@ function runImpeccable(args) {
         });
     });
 }
+function printEngineMissing() {
+    output.writeln();
+    output.writeln(output.warning('The bundled monodesign detection engine could not be found.'));
+    output.writeln();
+    output.writeln('The detector ships with @monoes/monodesign. Reinstall monomind to restore it:');
+    output.writeln(output.dim('  npm install -g monomind   # or: pnpm install (in a monomind checkout)'));
+    output.writeln();
+}
 // ─── detect subcommand ────────────────────────────────────────────────────────
 const detectSubcommand = {
     name: 'detect',
-    description: 'Detect design anti-patterns in HTML/CSS files using impeccable',
+    description: 'Detect design anti-patterns in HTML/CSS files using the bundled monodesign engine',
     options: [
         {
             name: 'target',
@@ -70,28 +91,96 @@ const detectSubcommand = {
         output.writeln();
         output.writeln(output.bold('Design Anti-Pattern Detection'));
         output.writeln(output.dim('─'.repeat(50)));
-        const available = await isImpeccableAvailable();
-        if (!available) {
-            output.writeln();
-            output.writeln(output.warning('impeccable is not installed.'));
-            output.writeln();
-            output.writeln('Install it to enable design anti-pattern detection:');
-            output.writeln(output.dim('  npm install -g impeccable'));
-            output.writeln();
-            output.writeln('Or run directly without installing:');
-            output.writeln(output.dim('  npx impeccable detect <file-or-dir>'));
-            output.writeln();
-            output.writeln(output.dim('impeccable checks for 46 known design anti-patterns across:'));
-            output.writeln(output.dim('  • slop  — AI tells: purple palettes, side-tabs, card grids, italic-serif heroes'));
-            output.writeln(output.dim('  • quality — spacing, hierarchy, readability, contrast, motion, typography'));
-            return { success: false, message: 'impeccable not installed' };
+        const cliPath = resolveMonodesignCli();
+        if (!cliPath) {
+            printEngineMissing();
+            return { success: false, message: 'monodesign detection engine not found' };
         }
         output.writeln(output.dim(`Scanning: ${target}`));
         output.writeln();
-        const forwardArgs = [target];
+        const forwardArgs = ['detect', target];
         if (jsonOutput)
             forwardArgs.push('--json');
-        const exitCode = await runImpeccable(forwardArgs);
+        const exitCode = await runMonodesign(cliPath, forwardArgs);
+        return { success: exitCode === 0, exitCode };
+    },
+};
+// ─── fix subcommand ───────────────────────────────────────────────────────────
+const fixSubcommand = {
+    name: 'fix',
+    description: 'Auto-fix design anti-patterns with a safe deterministic codemod, where one exists',
+    options: [
+        {
+            name: 'target',
+            short: 't',
+            type: 'string',
+            description: 'File or directory to fix',
+            default: '.',
+        },
+        {
+            name: 'dry-run',
+            type: 'boolean',
+            description: 'Print unified diffs of would-be changes; write nothing',
+        },
+        {
+            name: 'json',
+            type: 'boolean',
+            description: 'Output the fix report as JSON',
+        },
+        {
+            name: 'rule',
+            type: 'string',
+            description: 'Only fix the given rule ids (comma-separated)',
+        },
+    ],
+    examples: [
+        { command: 'monomind design fix', description: 'Auto-fix anti-patterns in the current directory' },
+        { command: 'monomind design fix -t ./src --dry-run', description: 'Preview fixes without writing' },
+        { command: 'monomind design fix --rule tight-leading,tiny-text', description: 'Fix only specific rules' },
+    ],
+    action: async (ctx) => {
+        const target = ctx.flags.target || ctx.args[0] || '.';
+        const dryRun = ctx.flags['dry-run'];
+        const jsonOutput = ctx.flags.json;
+        const rule = ctx.flags.rule;
+        output.writeln();
+        output.writeln(output.bold('Design Anti-Pattern Auto-Fix'));
+        output.writeln(output.dim('─'.repeat(50)));
+        const cliPath = resolveMonodesignCli();
+        if (!cliPath) {
+            printEngineMissing();
+            return { success: false, message: 'monodesign detection engine not found' };
+        }
+        output.writeln(output.dim(`Fixing: ${target}${dryRun ? ' (dry run)' : ''}`));
+        output.writeln();
+        const forwardArgs = ['fix', target];
+        if (dryRun)
+            forwardArgs.push('--dry-run');
+        if (jsonOutput)
+            forwardArgs.push('--json');
+        if (rule)
+            forwardArgs.push('--rule', rule);
+        const exitCode = await runMonodesign(cliPath, forwardArgs);
+        return { success: exitCode === 0, exitCode };
+    },
+};
+// ─── ignores subcommand ───────────────────────────────────────────────────────
+const ignoresSubcommand = {
+    name: 'ignores',
+    description: 'Manage monodesign detector ignore rules, files, and values',
+    examples: [
+        { command: 'monomind design ignores list', description: 'Show current ignore configuration' },
+        { command: 'monomind design ignores add-rule <rule-id>', description: 'Ignore a detector rule project-wide' },
+        { command: 'monomind design ignores add-file <path>', description: 'Exclude a file from detection' },
+        { command: 'monomind design ignores remove-rule <rule-id>', description: 'Re-enable an ignored rule' },
+    ],
+    action: async (ctx) => {
+        const cliPath = resolveMonodesignCli();
+        if (!cliPath) {
+            printEngineMissing();
+            return { success: false, message: 'monodesign detection engine not found' };
+        }
+        const exitCode = await runMonodesign(cliPath, ['ignores', ...ctx.args]);
         return { success: exitCode === 0, exitCode };
     },
 };
@@ -99,10 +188,12 @@ const detectSubcommand = {
 export const designCommand = {
     name: 'design',
     description: 'Design tooling: anti-pattern detection, OKLCH palette seeding, and design quality checks',
-    subcommands: [detectSubcommand, paletteSubcommand],
+    subcommands: [detectSubcommand, fixSubcommand, ignoresSubcommand, paletteSubcommand],
     examples: [
         { command: 'monomind design detect', description: 'Detect design anti-patterns' },
         { command: 'monomind design detect -t ./src --json', description: 'JSON output for CI' },
+        { command: 'monomind design fix -t ./src --dry-run', description: 'Preview safe auto-fixes' },
+        { command: 'monomind design ignores list', description: 'Manage detector ignore rules' },
         { command: 'monomind design palette', description: 'Pick an OKLCH brand seed color' },
         { command: 'monomind design palette --from "my-product"', description: 'Deterministic seed from product name' },
     ],
@@ -113,7 +204,9 @@ export const designCommand = {
         output.writeln();
         output.writeln('Subcommands:');
         output.printList([
-            'detect   - Detect design anti-patterns using impeccable',
+            'detect   - Detect design anti-patterns (bundled monodesign engine)',
+            'fix      - Auto-fix anti-patterns with a safe deterministic codemod, where one exists',
+            'ignores  - Manage detector ignore rules, files, and values',
             'palette  - OKLCH brand seed — returns anchor color + mood + composition strategy',
         ]);
         output.writeln();

package/packages/@monomind/cli/dist/src/commands/design-palette.d.ts

@@ -1,7 +1,6 @@
 /**
  * CLI Design Palette Command
  * OKLCH brand-seed picker — returns one anchor seed color + mood + composition strategy.
- * Ported from impeccable's palette.mjs (129 hand-curated seeds).
  *
  * github.com/monoes/monomind
  */

package/packages/@monomind/cli/dist/src/commands/design-palette.js

@@ -1,7 +1,6 @@
 /**
  * CLI Design Palette Command
  * OKLCH brand-seed picker — returns one anchor seed color + mood + composition strategy.
- * Ported from impeccable's palette.mjs (129 hand-curated seeds).
  *
  * github.com/monoes/monomind
  */
@@ -496,8 +495,8 @@ export const paletteSubcommand = {
         const idFlag = ctx.flags.id;
         const fromFlag = ctx.flags.from;
         const jsonFlag = ctx.flags.json;
-        // Respect IMPECCABLE_PALETTE_SEED env var as a fallback for --from
-        const fromKey = fromFlag || process.env['IMPECCABLE_PALETTE_SEED'];
+        // Respect MONODESIGN_PALETTE_SEED env var as a fallback for --from
+        const fromKey = fromFlag || process.env['MONODESIGN_PALETTE_SEED'];
         let seed;
         if (idFlag) {
             const found = SEEDS.find((s) => s.id === idFlag);