luckiest-co 1.0.0

package/.claude-plugin/plugin.json

@@ -0,0 +1,6 @@
+{
+  "name": "luckiest",
+  "description": "Plan, go, finish. Guided planning, progress dashboards, and your luckiest.co tribe inside Claude Code.",
+  "version": "0.1.0",
+  "author": { "name": "Luckiest" }
+}

package/README.md

@@ -0,0 +1,38 @@
+# Luckiest for Claude Code
+
+Luckiest brings your planning flow, tribe, and skill dashboard into Claude Code. Plan your work inside your editor, track progress, and collaborate with your tribe without leaving the CLI.
+
+Luckiest connects to your luckiest.co account, showing live skill bookmarks, tribe leaderboards, and guided planning workflows. All commands respect DRAFT, DOING, and DONE states tracked on luckiest.co.
+
+## Install
+
+```bash
+npx luckiest-co
+```
+
+Or add the plugin manually:
+```bash
+npx claude plugin add luckiest-co
+```
+
+## Commands
+
+| Command | What it does |
+|---------|------------|
+| `/luckiest start` | Begin a new skill or goal |
+| `/luckiest plan` | Guided planning for a skill or project |
+| `/luckiest go` | Move a bookmark to DOING |
+| `/luckiest finish` | Mark work done and close |
+| `/luckiest status` | Show current work state: DRAFT, DOING, or DONE |
+| `/luckiest skills` | List all your bookmarked skills |
+| `/luckiest home` | Jump to your luckiest.co home dashboard |
+| `/luckiest leaderboard` | See your tribe's weekly activity and progress |
+| `/luckiest helpers` | Find and request help from tribe members |
+| `/luckiest wishes` | See what your tribe is working toward |
+| `/luckiest charms` | View and use your skill boosters |
+
+## Requirements
+
+- Claude Code (CLI)
+- Active luckiest.co account
+- Account API key (set via `claude config`)

package/bin/install.js

@@ -0,0 +1,413 @@
+#!/usr/bin/env node
+
+// Forked from PAUL Framework's installer (bin/install.js), MIT licensed.
+// Rebranded for Luckiest, extended with a connection-key prompt and
+// owned-skill sync from luckiest.co. See ../LICENSE-THIRD-PARTY.md.
+
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+const readline = require('readline');
+const { execFileSync } = require('child_process');
+
+// Colors
+const cyan = '\x1b[36m';
+const green = '\x1b[32m';
+const yellow = '\x1b[33m';
+const red = '\x1b[31m';
+const dim = '\x1b[2m';
+const reset = '\x1b[0m';
+
+// Get version from package.json
+const pkg = require('../package.json');
+
+const banner = `
+${cyan}  ██╗     ██╗   ██╗ ██████╗██╗  ██╗██╗███████╗███████╗████████╗
+  ██║     ██║   ██║██╔════╝██║ ██╔╝██║██╔════╝██╔════╝╚══██╔══╝
+  ██║     ██║   ██║██║     █████╔╝ ██║█████╗  ███████╗   ██║
+  ██║     ██║   ██║██║     ██╔═██╗ ██║██╔══╝  ╚════██║   ██║
+  ███████╗╚██████╔╝╚██████╗██║  ██╗██║███████╗███████║   ██║
+  ╚══════╝ ╚═════╝  ╚═════╝╚═╝  ╚═╝╚═╝╚══════╝╚══════╝   ╚═╝${reset}
+
+  Luckiest ${dim}v${pkg.version}${reset}
+  Plan, go, finish. Your luckiest.co skills and tribe, inside Claude.
+`;
+
+// Parse args
+const args = process.argv.slice(2);
+const hasGlobal = args.includes('--global') || args.includes('-g');
+const hasLocal = args.includes('--local') || args.includes('-l');
+const syncOnly = args.includes('--sync-only');
+
+// Parse --config-dir argument
+function parseConfigDirArg() {
+  const configDirIndex = args.findIndex(arg => arg === '--config-dir' || arg === '-c');
+  if (configDirIndex !== -1) {
+    const nextArg = args[configDirIndex + 1];
+    if (!nextArg || nextArg.startsWith('-')) {
+      console.error(`  ${yellow}--config-dir requires a path argument${reset}`);
+      process.exit(1);
+    }
+    return nextArg;
+  }
+  const configDirArg = args.find(arg => arg.startsWith('--config-dir=') || arg.startsWith('-c='));
+  if (configDirArg) {
+    return configDirArg.split('=')[1];
+  }
+  return null;
+}
+const explicitConfigDir = parseConfigDirArg();
+const hasHelp = args.includes('--help') || args.includes('-h');
+
+console.log(banner);
+
+// Show help if requested
+if (hasHelp) {
+  console.log(`  ${yellow}Usage:${reset} npx luckiest-co [options]
+
+  ${yellow}Options:${reset}
+    ${cyan}-g, --global${reset}              Install globally (to Claude config directory)
+    ${cyan}-l, --local${reset}               Install locally (to ./.claude in current directory)
+    ${cyan}-c, --config-dir <path>${reset}   Specify custom Claude config directory
+    ${cyan}--sync-only${reset}               Skip install, only sync owned skills from luckiest.co
+    ${cyan}-h, --help${reset}                Show this help message
+
+  ${yellow}Examples:${reset}
+    ${dim}# Install to default ~/.claude directory${reset}
+    npx luckiest-co --global
+
+    ${dim}# Install to current project only${reset}
+    npx luckiest-co --local
+
+    ${dim}# Re-sync owned skills only (used by /luckiest skills)${reset}
+    npx luckiest-co --sync-only
+
+  ${yellow}What gets installed:${reset}
+    commands/luckiest/   - Slash commands (/luckiest:plan, /luckiest:go, etc.)
+    references/          - Vocabulary and chart-renderer references
+    templates/            - Brief templates
+    .claude-plugin/       - Plugin manifest
+
+  Owned skills purchased on luckiest.co are synced to ${dim}~/.claude/skills/<name>/${reset}.
+`);
+  process.exit(0);
+}
+
+/**
+ * Expand ~ to home directory
+ */
+function expandTilde(filePath) {
+  if (filePath && filePath.startsWith('~/')) {
+    return path.join(os.homedir(), filePath.slice(2));
+  }
+  return filePath;
+}
+
+/**
+ * Recursively copy directory, replacing paths in .md files
+ */
+function copyWithPathReplacement(srcDir, destDir, pathPrefix) {
+  fs.mkdirSync(destDir, { recursive: true });
+
+  const entries = fs.readdirSync(srcDir, { withFileTypes: true });
+
+  for (const entry of entries) {
+    const srcPath = path.join(srcDir, entry.name);
+    const destPath = path.join(destDir, entry.name);
+
+    if (entry.isDirectory()) {
+      copyWithPathReplacement(srcPath, destPath, pathPrefix);
+    } else if (entry.name.endsWith('.md')) {
+      // Replace ~/.claude/ with the appropriate prefix in markdown files
+      let content = fs.readFileSync(srcPath, 'utf8');
+      content = content.replace(/~\/\.claude\//g, pathPrefix);
+      fs.writeFileSync(destPath, content);
+    } else {
+      fs.copyFileSync(srcPath, destPath);
+    }
+  }
+}
+
+/**
+ * ~/.luckiest/key helpers. The key is NEVER echoed to stdout/logs and is
+ * only ever written to this one file, at mode 0600.
+ */
+function keyFilePath() {
+  return path.join(os.homedir(), '.luckiest', 'key');
+}
+
+function readSavedKey() {
+  try {
+    const raw = fs.readFileSync(keyFilePath(), 'utf8').trim();
+    return raw.length ? raw : null;
+  } catch {
+    return null;
+  }
+}
+
+function saveKey(key) {
+  const dir = path.join(os.homedir(), '.luckiest');
+  fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
+  const file = keyFilePath();
+  fs.writeFileSync(file, `${key}\n`, { mode: 0o600 });
+  try {
+    fs.chmodSync(file, 0o600);
+  } catch {
+    // best effort on platforms without chmod semantics
+  }
+}
+
+/**
+ * Prompt for the connection key. Input is not masked (no new dependency
+ * for that), but the value is never printed back and never logged.
+ */
+function promptKey() {
+  return new Promise((resolve) => {
+    const rl = readline.createInterface({
+      input: process.stdin,
+      output: process.stdout
+    });
+    rl.question(
+      `  Paste your luckiest.co connection key (starts with lk_mcp_), or press Enter to skip: `,
+      (answer) => {
+        rl.close();
+        resolve(answer.trim());
+      }
+    );
+  });
+}
+
+function apiBaseUrl() {
+  return (process.env.LUCKIEST_API_URL || 'https://luckiest.co').replace(/\/$/, '');
+}
+
+function hasUnzip() {
+  try {
+    execFileSync('unzip', ['-v'], { stdio: 'ignore' });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Sync owned skills from luckiest.co into ~/.claude/skills/<name>/.
+ * Never logs the key or the Authorization header.
+ */
+async function syncSkills() {
+  const key = readSavedKey();
+  if (!key) {
+    console.log(`  ${dim}No luckiest.co connection key saved yet. Run ${cyan}npx luckiest-co${dim} and paste one to sync your owned skills.${reset}`);
+    return;
+  }
+
+  const base = apiBaseUrl();
+  console.log(`  Syncing owned skills from ${cyan}${base}${reset}...\n`);
+
+  let skills;
+  try {
+    const res = await fetch(`${base}/api/skills/owned`, {
+      headers: { Authorization: `Bearer ${key}` }
+    });
+    if (!res.ok) {
+      console.log(`  ${yellow}Could not fetch owned skills (HTTP ${res.status}). Skipping sync.${reset}`);
+      return;
+    }
+    const body = await res.json();
+    skills = Array.isArray(body) ? body : body.skills;
+  } catch (err) {
+    console.log(`  ${yellow}Could not reach luckiest.co to sync skills: ${err.message}${reset}`);
+    return;
+  }
+
+  if (!skills || skills.length === 0) {
+    console.log(`  ${dim}No owned skills found for this key.${reset}`);
+    return;
+  }
+
+  const skillsRoot = path.join(os.homedir(), '.claude', 'skills');
+  fs.mkdirSync(skillsRoot, { recursive: true });
+  const unzipAvailable = hasUnzip();
+
+  const results = [];
+
+  for (const skill of skills) {
+    const { name, version, downloadUrl } = skill || {};
+    if (!name || !downloadUrl) {
+      console.log(`  ${yellow}Skipping a skill entry with missing name or downloadUrl.${reset}`);
+      continue;
+    }
+
+    // Sanitize skill name to prevent path traversal attacks
+    const safeName = path.basename(String(name || ''));
+    if (!safeName || safeName === '.' || safeName === '..' || safeName !== name) {
+      console.warn(`  ${yellow}Skipping skill with unsafe name: ${name}${reset}`);
+      continue;
+    }
+
+    try {
+      const zipRes = await fetch(downloadUrl);
+      if (!zipRes.ok) {
+        throw new Error(`download failed (HTTP ${zipRes.status})`);
+      }
+      const buf = Buffer.from(await zipRes.arrayBuffer());
+
+      if (unzipAvailable) {
+        const dest = path.join(skillsRoot, safeName);
+        fs.mkdirSync(dest, { recursive: true });
+        const tmpZip = path.join(os.tmpdir(), `luckiest-skill-${safeName}-${Date.now()}.zip`);
+        fs.writeFileSync(tmpZip, buf);
+        try {
+          execFileSync('unzip', ['-q', '-o', tmpZip, '-d', dest]);
+          results.push({ name, version: version || 'unknown', path: dest });
+        } finally {
+          fs.unlinkSync(tmpZip);
+        }
+      } else {
+        const zipPath = path.join(skillsRoot, `${safeName}.zip`);
+        fs.writeFileSync(zipPath, buf);
+        results.push({ name, version: version || 'unknown', path: `${zipPath} (unzip manually, unzip not found on PATH)` });
+      }
+    } catch (err) {
+      console.log(`  ${yellow}Warning: failed to install skill "${name}": ${err.message}${reset}`);
+    }
+  }
+
+  if (results.length === 0) {
+    console.log(`  ${yellow}No skills were installed.${reset}`);
+    return;
+  }
+
+  console.log(`\n  ${green}Skill sync summary:${reset}`);
+  const nameWidth = Math.max(4, ...results.map(r => r.name.length));
+  const versionWidth = Math.max(7, ...results.map(r => r.version.length));
+  console.log(`  ${'Name'.padEnd(nameWidth)}  ${'Version'.padEnd(versionWidth)}  Path`);
+  for (const r of results) {
+    console.log(`  ${r.name.padEnd(nameWidth)}  ${r.version.padEnd(versionWidth)}  ${r.path}`);
+  }
+  console.log('');
+}
+
+/**
+ * Install to the specified directory
+ */
+function install(isGlobal) {
+  const src = path.join(__dirname, '..');
+  const configDir = expandTilde(explicitConfigDir) || expandTilde(process.env.CLAUDE_CONFIG_DIR);
+  const defaultGlobalDir = configDir || path.join(os.homedir(), '.claude');
+  const claudeDir = isGlobal
+    ? defaultGlobalDir
+    : path.join(process.cwd(), '.claude');
+
+  const locationLabel = isGlobal
+    ? claudeDir.replace(os.homedir(), '~')
+    : claudeDir.replace(process.cwd(), '.');
+
+  // Path prefix for file references
+  const pathPrefix = isGlobal
+    ? (configDir ? `${claudeDir}/` : '~/.claude/')
+    : './.claude/';
+
+  console.log(`  Installing to ${cyan}${locationLabel}${reset}\n`);
+
+  // Copy commands/luckiest into commands/luckiest
+  const commandsDir = path.join(claudeDir, 'commands');
+  fs.mkdirSync(commandsDir, { recursive: true });
+
+  const commandsSrc = path.join(src, 'commands', 'luckiest');
+  const commandsDest = path.join(commandsDir, 'luckiest');
+  if (fs.existsSync(commandsSrc)) {
+    copyWithPathReplacement(commandsSrc, commandsDest, pathPrefix);
+    console.log(`  ${green}✓${reset} Installed commands/luckiest`);
+  }
+
+  // Copy references/, templates/, .claude-plugin/ into the target root
+  const topLevelDirs = ['references', 'templates', '.claude-plugin'];
+  for (const dir of topLevelDirs) {
+    const dirSrc = path.join(src, dir);
+    const dirDest = path.join(claudeDir, dir);
+    if (fs.existsSync(dirSrc)) {
+      copyWithPathReplacement(dirSrc, dirDest, pathPrefix);
+      console.log(`  ${green}✓${reset} Installed ${dir}`);
+    }
+  }
+
+  console.log(`
+  ${green}Done!${reset} Launch Claude Code and run ${cyan}/luckiest:plan${reset}.
+`);
+}
+
+/**
+ * Prompt for install location
+ */
+function promptLocation() {
+  return new Promise((resolve) => {
+    const rl = readline.createInterface({
+      input: process.stdin,
+      output: process.stdout
+    });
+
+    const configDir = expandTilde(explicitConfigDir) || expandTilde(process.env.CLAUDE_CONFIG_DIR);
+    const globalPath = configDir || path.join(os.homedir(), '.claude');
+    const globalLabel = globalPath.replace(os.homedir(), '~');
+
+    console.log(`  ${yellow}Where would you like to install?${reset}
+
+  ${cyan}1${reset}) Global ${dim}(${globalLabel})${reset}, available in all projects
+  ${cyan}2${reset}) Local  ${dim}(./.claude)${reset}, this project only
+`);
+
+    rl.question(`  Choice ${dim}[1]${reset}: `, (answer) => {
+      rl.close();
+      const choice = answer.trim() || '1';
+      resolve(choice !== '2');
+    });
+  });
+}
+
+async function main() {
+  if (syncOnly) {
+    await syncSkills();
+    return;
+  }
+
+  if (hasGlobal && hasLocal) {
+    console.error(`  ${yellow}Cannot specify both --global and --local${reset}`);
+    process.exit(1);
+  }
+
+  let isGlobal;
+  if (explicitConfigDir && hasLocal) {
+    console.error(`  ${yellow}Cannot use --config-dir with --local${reset}`);
+    process.exit(1);
+  } else if (hasGlobal) {
+    isGlobal = true;
+  } else if (hasLocal) {
+    isGlobal = false;
+  } else {
+    isGlobal = await promptLocation();
+  }
+
+  install(isGlobal);
+
+  const alreadyHasKey = !!readSavedKey();
+  if (!alreadyHasKey) {
+    const key = await promptKey();
+    if (key) {
+      if (!key.startsWith('lk_mcp_')) {
+        console.log(`  ${yellow}That doesn't look like a luckiest.co key (expected lk_mcp_...), but saving it anyway.${reset}`);
+      }
+      saveKey(key);
+      console.log(`  ${green}✓${reset} Key saved to ${dim}~/.luckiest/key${reset}\n`);
+    } else {
+      console.log(`  ${dim}Skipped. Run ${cyan}npx luckiest-co --sync-only${dim} later once you have a key.${reset}\n`);
+    }
+  }
+
+  await syncSkills();
+}
+
+main().catch((err) => {
+  console.error(`  ${red}Install failed: ${err.message}${reset}`);
+  process.exit(1);
+});

package/commands/luckiest/charms.md

@@ -0,0 +1,36 @@
+---
+description: Your charms balance and recent related activity.
+---
+
+Read `references/vocabulary.md` and `references/chart-renderer.md` first and follow them for all output in this command.
+
+## Step 1: Get the data
+
+Call the `overview` tool from the luckiest MCP server. Use the `charms` balance and scan `tribePulse` for any entries whose `event` text relates to charms (earning or spending).
+
+## Step 2: Render the dashboard
+
+Render one fenced code block following the chart-renderer grammar:
+
+1. Title line: `Charms`
+2. Balance line: `balance X` where X is the `charms` value from `overview`, right-aligned if paired with other numbers.
+3. If any charm-related entries exist in `tribePulse`, list them plainly, one per line, using the raw `event` text exactly as returned. Do not invent a friendlier phrasing.
+4. If there is no daily earn/spend history available (there is no history endpoint in this version), add this exact line: `History view coming soon.` Do not invent daily numbers, trends, or a chart of activity over time. Only render a bar chart of actual daily values if such data is actually returned by a tool; since none is available here, skip the bar chart and show the line above instead.
+5. Footer: `→ /luckiest charms`
+
+Example:
+
+```
+ Charms
+ balance 130
+ History view coming soon.
+ → /luckiest charms
+```
+
+Use only user-facing vocabulary from `references/vocabulary.md`. Never surface PLAN, APPLY, UNIFY, DRAFT, DOING, DONE, HANDOFF, or any internal term.
+
+## Step 3: Recommend next action
+
+End your response with exactly one line, nothing after it:
+
+Next: /luckiest home

package/commands/luckiest/finish.md

@@ -0,0 +1,40 @@
+---
+description: Wrap up, what shipped, what changed, what's next.
+---
+
+Read `references/vocabulary.md` first and follow it for all output in this command: plain language, no em dashes, no internal terms, one next-step recommendation at the end.
+
+## Step 1: Check that everything is done
+
+Call the `status` tool from the luckiest MCP server.
+
+If any task is still open (not complete), list those tasks for the user and stop here. Do not proceed to the rest of this command. End your response with exactly one line, nothing after it:
+
+Next: /luckiest go
+
+## Step 2: Compose the recap
+
+If every task is complete, write a short recap in chat with these sections:
+
+- **Shipped**: what got built or changed, in plain terms.
+- **Decisions**: any notable choices made along the way and why.
+- **Key files**: the main files touched, so the user knows where to look.
+- **Deferred**: anything explicitly pushed off, if applicable. Say "none" if there's nothing deferred.
+
+## Step 3: Close it out
+
+Call the `finish` tool from the luckiest MCP server with:
+
+```
+{ decisions, keyFiles, deferred }
+```
+
+using the same lists from your recap. This awards Charms and archives the history automatically.
+
+Report the Charms earned in friendly, plain terms, for example: "You earned 3 charms."
+
+## Step 4: Wrap up
+
+End your response with exactly one line, nothing after it:
+
+Next: /luckiest plan for the next piece, or /luckiest home to see where you stand.

package/commands/luckiest/go.md

@@ -0,0 +1,45 @@
+---
+description: Run your plan, one task at a time, checked as it goes.
+---
+
+Read `references/vocabulary.md` first and follow it for all output in this command: plain language, no em dashes, no internal terms, one next-step recommendation at the end.
+
+## Step 1: Load the plan
+
+Call the `status` tool from the luckiest MCP server. This is a zero-context resume, treat its result as the full picture of where things stand: don't assume anything about prior state beyond what it returns.
+
+## Step 2: Execute in-session
+
+Do all task work yourself, in this session, message by message.
+
+- Forbidden: spawning subagents to execute tasks. Never hand off the actual work of a ready task to a subagent.
+- Allowed: spawning subagents for research only (for example, looking something up, exploring the codebase for context). The work itself, writing code, making changes, running commands, stays in this session.
+
+## Step 3: Work through ready tasks, one at a time
+
+Take the ready tasks one at a time, in order. For each one:
+
+1. Do the work using the task's suggested skill. If that skill is installed, invoke it via the Skill tool. If it isn't installed, do the work directly without it.
+2. Check your result against the task's "done means..." line. Don't move on until it's actually met.
+3. If the result is something the user can try themselves (a page, a feature, a flow), ask exactly this: "Try it yourself, does it work? yes / needs fixes." Wait for their answer.
+4. On a pass, call the `apply` tool with `{ taskId }` for that task, then call the `verify` tool with `{ results: [{ taskId, pass: true }] }`.
+5. On a fail, fix the problem before moving on to the next task. Only call `verify` with `pass: false` for that task if the user explicitly chooses to defer the fix instead of having you fix it now.
+
+Only move to the next ready task once the current one is applied and verified (or deferred).
+
+## Step 4: Stop conditions
+
+Pause and ask the user before doing any of the following, even if it seems like the obvious next step:
+
+- Any destructive action (deleting data, dropping tables, force-pushing, overwriting files with no way back).
+- Adding a new dependency.
+- Any schema change.
+
+If the session has to end before the plan is done, call the `pause` tool with `{ reason }`, a one-line reason describing where things were left.
+
+## Step 5: Wrap up
+
+End your response with exactly one line, nothing after it.
+
+- If all tasks are done: `Next: /luckiest finish to wrap up.`
+- Otherwise: `Next: <the next task title>.`

package/commands/luckiest/helpers.md

@@ -0,0 +1,64 @@
+---
+description: See who needs a hand right now, and claim a request to help.
+---
+
+Read `references/vocabulary.md` and `references/chart-renderer.md` first and follow them for all output in this command.
+
+## Step 1: Get the data
+
+Call the `overview` tool from the luckiest MCP server to get the `openAssists` count. If an assist listing tool is available that returns the actual open requests (title, poster, wish reward, and id for each), use it and prefer that list over the raw count. In v1 a per-request listing may not be available through the MCP server: in that case, do not invent requests. Show the count and point the user to the full board, as described in Step 2.
+
+## Step 2: Render the open requests
+
+If the count is zero and no requests come back, output nothing except:
+
+```
+No open requests right now.
+```
+
+Then end with:
+
+```
+Next: /luckiest home
+```
+
+Do not proceed further.
+
+If you have the count but no per-request details (no listing tool available), render one fenced block with the count and an honest pointer, then stop:
+
+```
+ Needs Help
+ open requests 3
+ Full board and claiming at luckiest.co/dashboard
+ → /luckiest home
+```
+
+and end with `Next: open luckiest.co to claim a request`.
+
+If there are open requests with details, render one fenced code block following the chart-renderer grammar:
+
+1. Title line: `Needs Help (X open)` where X is the number of requests actually listed.
+2. One entry per request, each showing:
+   - Title of the request
+   - Poster name
+   - Wish reward, right-aligned, e.g. `reward 8 wishes`
+   - A claim line directly under it: `→ tell me "claim <id>" and I'll pick it up with respond_to_assist`
+
+Example:
+
+```
+ Needs Help (2 open)
+ Fix the onboarding copy         posted by Priya      reward 8 wishes
+ → tell me "claim a12" and I'll pick it up with respond_to_assist
+
+ Review the pricing page         posted by Marcus     reward 5 wishes
+ → tell me "claim a13" and I'll pick it up with respond_to_assist
+```
+
+Use only user-facing vocabulary from `references/vocabulary.md`. Never surface PLAN, APPLY, UNIFY, DRAFT, DOING, DONE, HANDOFF, or any internal term. Do not fabricate requests, posters, or rewards beyond what the tools return.
+
+## Step 3: Recommend next action
+
+End your response with exactly one line, nothing after it:
+
+Next: tell me "claim <id>" for the request you want to help with

package/commands/luckiest/home.md

@@ -0,0 +1,43 @@
+---
+description: The community dashboard. Wishes and charms, plan progress, tribe pulse, and who needs help.
+---
+
+Read `references/vocabulary.md` and `references/chart-renderer.md` first and follow them for all output in this command.
+
+## Step 1: Get the data
+
+Call the `overview` tool from the luckiest MCP server. It returns `{ wishes, charms, loop, openAssists, tribePulse }`.
+
+## Step 2: Render the dashboard
+
+Render one fenced code block following the chart-renderer grammar, with four boxes in this order. Separate boxes with a blank line.
+
+1. **Wishes + Charms box**
+   - Title line: `Wishes & Charms`
+   - One line showing the two balances, aligned columns, thousands separators, for example `wishes 42        charms 130`
+   - Footer: `→ /luckiest wishes`
+
+2. **Active plan progress box**
+   - Title line: `Plan Progress`
+   - If `loop` is null, one line: `No plan yet.`
+   - If `loop` is present, one progress bar line using `█` (filled) and `░` (empty), exactly 20 chars total, with `done/total` right-aligned, for example `██████░░░░░░░░░░░░  3/5`, plus the phase name if present.
+   - Footer: if `loop` is present, `→ /luckiest go`; if `loop` is null, `→ /luckiest status`
+
+3. **Tribe pulse box**
+   - Title line: `Tribe Pulse`
+   - One line per entry in `tribePulse`, showing the member name and the raw `event` string exactly as returned. Do not rewrite, embellish, or invent a friendlier phrasing for the event text. If `tribePulse` is empty, one line: `No recent activity.`
+   - Footer: `→ /luckiest leaderboard`
+
+4. **Needs help box**
+   - Title line: `Needs Help`
+   - One line: `open requests X` where X is `openAssists`.
+   - Footer: `→ /luckiest helpers`
+
+Use only user-facing vocabulary from `references/vocabulary.md`. Never surface PLAN, APPLY, UNIFY, DRAFT, DOING, DONE, HANDOFF, or any internal term.
+
+## Step 3: Recommend next action
+
+End your response with exactly one line, nothing after it, based on whether a plan is active:
+
+- If `loop` is present (active plan): `Next: /luckiest go`
+- If `loop` is null (no active plan): `Next: /luckiest plan`

package/commands/luckiest/leaderboard.md

@@ -0,0 +1,37 @@
+---
+description: See how the tribe ranks. Top scores, one bar chart.
+---
+
+Read `references/vocabulary.md` and `references/chart-renderer.md` first and follow them for all output in this command.
+
+## Step 1: Get the data
+
+Call the `tribe_leaderboard` tool from the luckiest MCP server. If the tool accepts a range argument and the user specified one (e.g. `/luckiest leaderboard 30d`), pass it through. Otherwise call it with no range argument.
+
+## Step 2: Render the leaderboard
+
+Render one fenced code block following the chart-renderer grammar.
+
+1. **Range header**: only include a `[ 7 Days ]  30 Days  All`-style range header if the tool's response indicates it supports ranges (e.g. it echoes back a range or accepts one). If there is no evidence the tool supports ranges, omit the header entirely. Do not invent range options.
+
+2. **Ranked bar chart**: one line per member, in rank order, with columns for rank, name, and a horizontal bar representing score. Use `█` for filled, `░` for empty, width 20 chars, value right-aligned. For example:
+
+```
+ Tribe Leaderboard
+ 1  Priya   ████████████████░░░░  820
+ 2  Sam     ██████████████░░░░░░  710
+ 3  Marcus  ████████░░░░░░░░░░░░  405
+ → /luckiest leaderboard
+```
+
+3. **Movement arrows**: only add a movement indicator (e.g. `▲2`, `▼1`, `=`) next to a member's name if the tool response includes prior-rank data for that member. If no prior-rank data is present anywhere in the response, omit movement indicators entirely for all members. Do not fabricate or estimate movement.
+
+4. **Footer**: last line in the block is `→ /luckiest leaderboard` (or the range-qualified form if a range was passed, e.g. `→ /luckiest leaderboard 30d`).
+
+Use only user-facing vocabulary from `references/vocabulary.md`. Never surface PLAN, APPLY, UNIFY, DRAFT, DOING, DONE, HANDOFF, or any internal term.
+
+## Step 3: Recommend next action
+
+End your response with exactly one line, nothing after it:
+
+Next: /luckiest helpers

package/commands/luckiest/merge.md

@@ -0,0 +1,38 @@
+---
+description: Merge two overlapping skills into one, after you review the diff.
+---
+
+Read `references/vocabulary.md` first and follow it for all output in this command: plain language, no em dashes, no internal terms, one next-step recommendation at the end.
+
+## Step 1: Get the two skill ids
+
+If the user named both skills (e.g. `/luckiest merge luckiest-copywriting their-copy-skill`), use those as `ourSkillId` and `theirSkillId`. Otherwise ask which two skills to merge, or point them to `/luckiest overlaps` to find a pair first.
+
+## Step 2: Draft the merge
+
+Call the `draft_merge` tool from the luckiest MCP server with `{ ourSkillId, theirSkillId }`.
+
+This does not install or archive anything yet. Show the user the returned diff plainly, as a fenced code block. Do not summarize it away, they need to see exactly what changes.
+
+Ask exactly one approval question:
+
+"Use this merged version? yes / no"
+
+Wait for the answer.
+
+- If no, stop here. End with the wrap-up line in Step 4.
+- If yes, continue to Step 3.
+
+## Step 3: Apply the merge
+
+Call the `apply_merge` tool from the luckiest MCP server with `{ ourSkillId, theirSkillId, mergedName, mergedContent }`, using the merged name and content from the draft in Step 2.
+
+Tell the user plainly what happened: the two original skill directories were archived (moved to `~/.claude/luckiest-archive/`, never deleted) and the merged skill was installed under `mergedName`.
+
+## Step 4: Wrap up
+
+End your response with exactly one line, nothing after it:
+
+```
+Next: /luckiest skills
+```

package/commands/luckiest/overlaps.md

@@ -0,0 +1,50 @@
+---
+description: Find installed skills that overlap with your own, and resolve them.
+---
+
+Read `references/vocabulary.md` first and follow it for all output in this command: plain language, no em dashes, no internal terms, one next-step recommendation at the end.
+
+## Step 1: Pick a skill to check
+
+If the user named a skill (e.g. `/luckiest overlaps luckiest-copywriting`), use that as `skillId`. Otherwise, list the installed `luckiest-*` skills (same discovery as `/luckiest skills`, directories under `~/.claude/skills/`) and ask which one to check.
+
+## Step 2: Scan
+
+Call the `scan_overlaps` tool from the luckiest MCP server with `{ skillId }`.
+
+If it returns no overlapping pairs, output exactly:
+
+```
+No overlaps found for <skillId>.
+```
+
+Then skip to Step 4.
+
+## Step 3: Show what overlaps and offer a resolution
+
+List each overlapping pair plainly, one per entry, showing the other skill's id and its tag-overlap score (and description-similarity score if the tool returned one). Do not invent a score if none was returned.
+
+```
+Overlaps with <skillId>:
+• <theirSkillId>  tag overlap 0.82
+```
+
+For each pair, tell the user their three options in plain terms and how to pick one:
+
+- "keep both" — leave both installed, the router picks the best fit per task.
+- "shadow" — yours stays authoritative, theirs becomes a fallback.
+- "merge" — draft a combined skill for review (nothing installs yet).
+
+Tell them to reply with one of those words plus which pair, e.g. `"merge with <theirSkillId>"`.
+
+If the user picks "keep both" or "shadow", call `resolve_overlap` with `{ ourSkillId, theirSkillId, resolution }` using their choice, then confirm what happened in one line.
+
+If the user picks "merge", do not call `resolve_overlap` here. Instead tell them to run `/luckiest merge <skillId> <theirSkillId>` to draft and review it.
+
+## Step 4: Wrap up
+
+End your response with exactly one line, nothing after it:
+
+```
+Next: /luckiest skills
+```

package/commands/luckiest/plan.md

@@ -0,0 +1,55 @@
+---
+description: Plan your next piece of work. Guided questions, then a plan Claude can run.
+---
+
+Read `references/vocabulary.md` first and follow it for all output in this command: plain language, no em dashes, no internal terms, one next-step recommendation at the end.
+
+## Step 1: Gather context
+
+Check whether `.luckiest/BRIEF.md` exists in the current project. If it exists, read it and use it as context for the interview below (what they're building, who it's for, what winning looks like). If it does not exist, continue without it.
+
+## Step 2: Check for active work
+
+Call the `status` tool from the luckiest MCP server.
+
+- If the returned state's position is active (already in progress), stop here. Tell the user a plan is already active and offer `/luckiest go` to resume it instead. Do not stage a new plan over an active one unless the user explicitly confirms they want to replace it. If they confirm, continue to Step 3.
+- Otherwise, continue to Step 3.
+
+## Step 3: Run the interview
+
+Ask ONE question at a time, waiting for the answer before asking the next:
+
+1. What outcome do you want this week?
+
+Use the answer (plus the brief, if present) to shape a draft task list of 3 to 7 tasks. Each task title must be a single clean line under 200 characters, describing one piece of work. Do not append "done means" text or any acceptance-criteria text to the title.
+
+For each draft task, call the `skill_router` tool from the luckiest MCP server to suggest a matching owned skill for that task. Attach the suggested skill(s) to the task.
+
+For each task, state a one-line "done means..." in chat (not in the title, not stored anywhere) so the user sees what complete looks like for that task.
+
+## Step 4: Present the plan
+
+Show the full draft plan: each task's title, its suggested skill(s), and its "done means..." line. Then ask exactly one approval question, nothing else:
+
+"Here's your plan, good to go?"
+
+Wait for the answer.
+
+- If the user wants changes, revise the plan and ask the same approval question again.
+- If the user says yes, continue to Step 5.
+
+## Step 5: Stage the plan
+
+Call the `plan` tool from the luckiest MCP server with:
+
+```
+{ phase: <short phase name if any>, tasks: [{ title, skills }] }
+```
+
+Include at most 25 tasks. Each title must stay under 200 characters. Do not include acceptance criteria or "done means" text in any task field.
+
+## Step 6: Wrap up
+
+End your response with exactly one line, nothing after it:
+
+Next: /luckiest go to start.

package/commands/luckiest/skills.md

@@ -0,0 +1,53 @@
+---
+description: Your skills, list what's installed, pull new purchases.
+---
+
+Read `references/vocabulary.md` first and follow it for all output in this command. Never delete skills.
+
+## Step 1: List installed luckiest skills
+
+First, identify all directories in `~/.claude/skills/` that match the pattern `luckiest-*`. For each one:
+
+1. Read its `SKILL.md` file
+2. Extract the one-line `description:` value from the YAML frontmatter
+3. Display the skill name and description as a clean list
+
+Format each line as:
+```
+• <skill-name>: <one-line description>
+```
+
+If no luckiest skills are installed, output:
+```
+No luckiest skills installed yet. Use /luckiest skills sync to pull your purchases from luckiest.co.
+```
+
+Then jump to Step 3.
+
+## Step 2: Offer sync
+
+After the list, add a blank line, then this prompt:
+
+```
+You can pull newly purchased skills by replying "sync" below.
+```
+
+## Step 3: Handle sync request
+
+If the user replies "sync" or similar intent:
+
+1. Run this command via Bash: `npx luckiest-co --sync-only`
+2. Report what was added (skill names and versions) from the command output
+3. If no new skills were synced, acknowledge that the installation is already up to date
+
+If the user does not request sync, skip this step.
+
+## Step 4: Next line
+
+End your response with exactly one line, nothing after it:
+
+```
+Next: /luckiest plan
+```
+
+Never modify or delete any installed skills. This command is read-only except for the sync operation.

package/commands/luckiest/start.md

@@ -0,0 +1,45 @@
+---
+description: Tell me about your project, a short interview that writes your Brand Brief.
+---
+
+Read `references/vocabulary.md` first and follow it for all output in this command: plain language, no em dashes, no internal terms, one next-step recommendation at the end.
+
+## Step 1: Check for an existing brief
+
+Check whether `.luckiest/BRIEF.md` exists in the current project.
+
+- If it exists, read it and show the user a short summary (what they're building, who it's for, what winning looks like). Then ask: "Keep this brief as is, or update it?" Wait for their answer.
+  - If they choose to keep it, skip straight to the sync step below and end the command.
+  - If they choose to update it, continue to the interview below, but only ask about the sections they want to change.
+- If it does not exist, continue to the interview below.
+
+Never overwrite `.luckiest/BRIEF.md` silently. The user always gets to see what's there first and decide.
+
+## Step 2: Run the interview
+
+Ask the following questions ONE at a time, in order, waiting for the answer before asking the next. There are at most 6 questions. Tell the user up front that any question can be skipped by answering "skip."
+
+1. What are you building?
+2. Who is it for?
+3. What does winning look like in 30 days?
+4. What tone or voice should this have?
+5. Is there anything that must not change?
+6. Any links to share (designs, docs, prior work)?
+
+Keep the tone conversational, not a form. Ask one question, read the reply, then move to the next. Don't dump all six at once.
+
+## Step 3: Write the brief
+
+Read `templates/BRIEF.md` (in this plugin) for the section structure. Each section carries an HTML-comment prompt like `<!-- filled from the /luckiest start interview -->`. Fill each section in using the interview answers, in the user's own words where possible. If the user skipped a question, leave that section's `<!-- ... -->` comment in place rather than inventing content.
+
+Write the result to `.luckiest/BRIEF.md` in the current project (create the `.luckiest/` directory if it doesn't exist).
+
+## Step 4: Sync
+
+Call the `pause` tool from the luckiest MCP server with a reason like: `Brief created: <one-line summary of what they're building>`. This notes in the session bookmark that the brief now exists.
+
+## Step 5: Wrap up
+
+End your response with exactly one line, nothing after it:
+
+Next: /luckiest plan to plan your first work.

package/commands/luckiest/status.md

@@ -0,0 +1,55 @@
+---
+description: Where you are. Progress, tasks, and your one next step.
+---
+
+Read `references/vocabulary.md` and `references/chart-renderer.md` first and follow them for all output in this command.
+
+## Step 1: Check for a plan
+
+Call the `status` tool from the luckiest MCP server.
+
+If the returned state is null (no active plan), output nothing except these two lines, in order:
+
+```
+No plan yet. Start with /luckiest plan.
+```
+
+Then end with:
+
+```
+Next: /luckiest plan
+```
+
+Do not proceed further.
+
+## Step 2: Render the status dashboard
+
+If a plan exists, render one fenced code block following the chart-renderer grammar. The block MUST include:
+
+1. **Plan phase and header**: First line shows the plan's phase name (if present) or a generic title like "Your Work".
+2. **Progress bar**: One line with format `█` (filled) and `░` (empty) chars, exactly 20 chars total, with the count `done/total` right-aligned. Example: `██████░░░░░░░░░░░░  3/5`
+3. **Task lines**: One line per task in the plan's task list. Each line shows:
+   - Task title (truncate to fit on line)
+   - Status glyph: `✓` for done, `▸` for doing, `·` for ready, `?` for assist
+4. **Pass rate (if any)**: If the state includes any verified task results, add a line showing pass rate in the format `pass rate: X/Y` where X is completed verifications and Y is total tasks.
+5. **Bookmark line (if paused)**: If the state includes a bookmark (pause), add a line showing the bookmark message.
+6. **Footer**: Last line in the block ends with the command to check status again (e.g. `→ /luckiest status`).
+
+Use only the user-facing vocabulary from `references/vocabulary.md`. Never surface PLAN, APPLY, UNIFY, DRAFT, DOING, DONE, HANDOFF, or any internal term.
+
+Map each task's status to a glyph (these are the task status values, not the plan position):
+- "done" -> `✓`
+- "doing" -> `▸`
+- "ready" -> `·`
+- "assist" -> `?`
+- "blocked" -> `✗`
+
+## Step 3: Recommend next action
+
+End your response with exactly one line, nothing after it, derived from the MCP `nextAction` field:
+
+```
+Next: <nextAction>
+```
+
+If nextAction is null or empty, default to the most logical next step based on the current state (e.g., `Next: /luckiest go` if tasks are ready).

package/commands/luckiest/updates.md

@@ -0,0 +1,47 @@
+---
+description: Check for updates to your installed luckiest skills and plugin.
+---
+
+Read `references/vocabulary.md` first and follow it for all output in this command: plain language, no em dashes, no internal terms, one next-step recommendation at the end.
+
+## Step 1: Check for updates
+
+Call the `check_updates` tool from the luckiest MCP server.
+
+## Step 2: Report what's available
+
+If no updates are available, output exactly:
+
+```
+Everything is up to date.
+```
+
+Then skip to Step 3.
+
+If updates are available, list each one plainly, one per line, using only what the tool returns (skill or plugin name, current version, available version). Do not invent version numbers or changelog details that weren't returned. For example:
+
+```
+Updates available:
+• luckiest-copywriting  1.2.0 → 1.3.0
+• luckiest-cro          2.0.1 → 2.1.0
+```
+
+If any update includes a changelog or summary field in the tool response, show it as a short indented line under that entry. Do not fabricate one if it's missing.
+
+## Step 3: Offer to sync
+
+If updates were found, add a blank line, then:
+
+```
+You can pull these by replying "sync" below.
+```
+
+If the user replies "sync" or similar intent, run this command via Bash: `npx luckiest-co --sync-only`, then report what was actually updated from the command output.
+
+## Step 4: Wrap up
+
+End your response with exactly one line, nothing after it:
+
+```
+Next: /luckiest skills
+```

package/commands/luckiest/vouch.md

@@ -0,0 +1,33 @@
+---
+description: Request or approve a warm intro to someone outside your tribe.
+---
+
+Read `references/vocabulary.md` first and follow it for all output in this command: plain language, no em dashes, no internal terms, one next-step recommendation at the end.
+
+## Step 1: Figure out the intent
+
+- If the user is asking for an intro to someone (e.g. `/luckiest vouch <targetId>`, or "I need a warm intro to X"), go to Step 2.
+- If the user is approving a vouch someone asked them for (e.g. "approve vouch <vouchId>", or they were told about a pending vouch elsewhere), go to Step 3.
+- If neither is clear, ask which one they mean.
+
+## Step 2: Request a warm intro
+
+Call the `request_vouch` tool from the luckiest MCP server with `{ targetId }`. If this request is tied to an open assist request, include `assistRequestId` too.
+
+This asks a shared 1st-degree tribe member (someone in your direct tribe who also knows the target) to vouch for you before you can reach a 3rd-degree person directly.
+
+Report plainly that the request was sent and who needs to approve it, if the tool response says.
+
+## Step 3: Approve a vouch
+
+Call the `approve_vouch` tool from the luckiest MCP server with `{ vouchId }`.
+
+Confirm plainly that the vouch was approved and the intro can proceed.
+
+## Step 4: Wrap up
+
+End your response with exactly one line, nothing after it:
+
+```
+Next: /luckiest helpers
+```

package/commands/luckiest/wishes.md

@@ -0,0 +1,36 @@
+---
+description: Your wishes balance and recent related activity.
+---
+
+Read `references/vocabulary.md` and `references/chart-renderer.md` first and follow them for all output in this command.
+
+## Step 1: Get the data
+
+Call the `overview` tool from the luckiest MCP server. Use the `wishes` balance and scan `tribePulse` for any entries whose `event` text relates to wishes (earning or spending).
+
+## Step 2: Render the dashboard
+
+Render one fenced code block following the chart-renderer grammar:
+
+1. Title line: `Wishes`
+2. Balance line: `balance X` where X is the `wishes` value from `overview`, right-aligned if paired with other numbers.
+3. If any wish-related entries exist in `tribePulse`, list them plainly, one per line, using the raw `event` text exactly as returned. Do not invent a friendlier phrasing.
+4. If there is no daily earn/spend history available (there is no history endpoint in this version), add this exact line: `History view coming soon.` Do not invent daily numbers, trends, or a chart of activity over time. Only render a bar chart of actual daily values if such data is actually returned by a tool; since none is available here, skip the bar chart and show the line above instead.
+5. Footer: `→ /luckiest wishes`
+
+Example:
+
+```
+ Wishes
+ balance 42
+ History view coming soon.
+ → /luckiest wishes
+```
+
+Use only user-facing vocabulary from `references/vocabulary.md`. Never surface PLAN, APPLY, UNIFY, DRAFT, DOING, DONE, HANDOFF, or any internal term.
+
+## Step 3: Recommend next action
+
+End your response with exactly one line, nothing after it:
+
+Next: /luckiest charms

package/package.json

@@ -0,0 +1,9 @@
+{
+  "name": "luckiest-co",
+  "version": "1.0.0",
+  "description": "Luckiest for Claude Code: plan, go, finish. Your luckiest.co skills and tribe, inside Claude.",
+  "bin": { "luckiest-co": "./bin/install.js" },
+  "files": ["bin", "commands", "references", "templates", ".claude-plugin"],
+  "license": "MIT",
+  "engines": { "node": ">=18" }
+}

package/references/chart-renderer.md

@@ -0,0 +1,31 @@
+# Chart Renderer: Shared Visual Grammar
+
+All dashboard commands use this grammar for rendering data visualizations.
+
+## Grammar Rules
+
+Render dashboards as fenced code blocks using this grammar:
+- Section box: title line, then content, no borders needed beyond blank lines.
+- Horizontal bar: `█` for filled, `░` for empty, width 20 chars, value right-aligned.
+- Numbers: aligned columns, thousands separators.
+- Range header when applicable: `[ 7 Days ]  30 Days  All` with the active range bracketed.
+- Footer line naming the drill-down command, e.g. `→ /luckiest wishes 30d`.
+
+## Example
+
+```
+ Wishes                                [ 7 Days ]
+ balance 42        earned 12       spent 5
+ 06-28 ████████░░░░░░░░░░░░  4
+ 06-29 ██████████████░░░░░░  7
+ 07-01 ██░░░░░░░░░░░░░░░░░░  1
+ → /luckiest wishes 30d
+```
+
+## Implementation Notes
+
+- Each bar is exactly 20 filled/empty blocks.
+- Values are right-aligned after the bar.
+- Column headers are spaced evenly with at least 2 spaces between.
+- The footer command should match the context (e.g., `/luckiest wishes 30d` for a wishes dashboard).
+- Use single-space line breaks between sections for clarity.

package/references/vocabulary.md

@@ -0,0 +1,35 @@
+# Vocabulary: User-Facing Terms
+
+Every command file MUST read this file and follow it in all output.
+
+## Internal Term -> User-Facing Term Mapping
+
+| Internal | User-Facing |
+|----------|-------------|
+| PLAN | plan |
+| APPLY | go |
+| UNIFY | finish |
+| skill_loop status | status |
+| DRAFT | in progress |
+| DOING | active |
+| DONE | complete |
+| UAT | testing |
+| AC | requirements |
+| HANDOFF | ready for review |
+
+## Hard Rules
+
+1. **Never show internal terms to the user.** All output must use user-facing vocabulary only. Never surface PLAN, APPLY, UNIFY, skill_loop, UAT, AC, HANDOFF, DRAFT, DOING, or any internal database term in user-visible output.
+
+2. **Exactly one suggested next action per response.** Every command output ends with a single next-step recommendation in the format: `Next: <one action>`
+
+3. **Plain language, no jargon, no em dashes.** Use direct, accessible language. No em dashes. No filler phrases. No marketing speak.
+
+## Interpretation Guide
+
+- **"done means"**: A feature is complete when it's tested, documented, and ready for users. Not partial or draft.
+- **"bookmark"**: Save progress state (current plan, step count, completion %) so users can resume later.
+- **plan**: The complete feature spec and acceptance criteria.
+- **go**: Execute the next step of the plan.
+- **finish**: Mark the feature complete and document results.
+- **status**: Check where you are in the feature work.

package/templates/BRIEF.md

@@ -0,0 +1,23 @@
+# Brand Brief
+
+<!-- filled from the /luckiest start interview -->
+
+## What you're building
+
+<!-- One sentence: the feature or product in user terms -->
+
+## Who it's for
+
+<!-- The person or role this is built for -->
+
+## What winning looks like
+
+<!-- 2-3 bullet points: specific outcomes or behaviors that prove success -->
+
+## Voice & constraints
+
+<!-- How should this communicate? Any brand voice, tone, or technical limits -->
+
+## Links & assets
+
+<!-- Design files, research docs, previous similar work, reference links -->