smashspace 0.1.2 → 0.1.4

package/README.md

@@ -28,9 +28,31 @@ The token is delivered to a local loopback port and saved to
 `~/.config/smash/credentials.json`. The same credential is used by the MCP
 server below. (Headless? use `smash login --token <PAT>`.)
 
+## Onboard a project for agents: `smash init`
+
+Run once per repo to scaffold everything agents (Claude Code / Codex) need to
+operate SmashSpace as the task backbone — no manual copying:
+
+```bash
+smash init --board-id b_xxxxxxxx
+```
+
+It writes (and is safe to re-run — existing config is kept unless `--force`):
+
+- `.claude/skills/smash/SKILL.md` + `.codex/skills/smash/SKILL.md` — the
+  SmashSpace Operator playbook (CLI/MCP usage + Inbox→Todo→Doing→Review→Done
+  workflow + safety rules). Always refreshed to the installed CLI version.
+- `.smashspace.json` — pins the instance + board.
+- `.mcp.json` — wires the `smashspace` MCP server (merged, other servers kept).
+
+Flags: `--skills-only` (just the operator skill), `--no-mcp`, `--force`,
+`--board-id <id>`. Then `smash login` once on the machine and the agents are
+ready.
+
 ## Project config: `.smashspace.json`
 
-Drop this at your repo root so `smash` knows which board to operate on:
+`smash init` writes this for you; drop it at your repo root manually if you
+prefer, so `smash` knows which board to operate on:
 
 ```json
 {

package/dist/smash.mjs

@@ -3392,10 +3392,10 @@ var {
 import { spawn } from "node:child_process";
 import { createServer } from "node:http";
 import { randomBytes } from "node:crypto";
-import { readFile as readFile2, writeFile as writeFile2 } from "node:fs/promises";
+import { mkdir as mkdir2, readFile as readFile2, writeFile as writeFile2 } from "node:fs/promises";
 import { platform as platform2 } from "node:os";
 import { createInterface } from "node:readline/promises";
-import { relative } from "node:path";
+import { relative, join as join3, dirname as dirname3 } from "node:path";
 import { stdin, stdout } from "node:process";
 
 // ../../shared/board-registry.ts
@@ -3572,6 +3572,219 @@ function resolveBoardEntry(config, label) {
   return entry;
 }
 
+// ../../cli/templates.ts
+var SMASH_SKILL_MD = `---
+name: smash
+description: Operate SmashSpace task boards from the terminal and MCP. Use when the user asks for /smash list, /smash inbox, /smash todo-dig, /smash todo-dev, /smash review, task-board triage, card development, card review, or moving SmashSpace cards between Inbox/Todo/Doing/Review/Done.
+---
+
+# SmashSpace Operator
+
+Use this skill to run repeatable workflows against a SmashSpace task board.
+
+SmashSpace is a Cloudflare-native Kanban where people work in the UI and AI
+agents work through the CLI, MCP, and HTTP API on the **same** data.
+Product: <https://smashspace.app>.
+
+## How to reach the board
+
+Operate through the **\`smashspace-mcp\` MCP tools** when available; otherwise fall
+back to the **\`smash\` CLI**. Do **not** hit the HTTP API with \`curl\` or a raw
+browser \u2014 the CLI and MCP are the supported surfaces and they resolve auth and
+the target board for you.
+
+- CLI install: \`npm i -g smashspace\` (then \`smash --help\`)
+- MCP server: \`smashspace-mcp\` (exposes \`smash_*\` tools, same token as the CLI)
+- Sign in once per machine: \`smash login\` (browser approval; token saved to
+  \`~/.config/smash/credentials.json\` and reused by MCP)
+
+### Which board am I on?
+
+\`smash\` is **directory-aware**: it walks up from the current directory to the
+nearest \`.smashspace.json\`. **Always confirm context before acting:**
+
+\`\`\`bash
+smash status          # config file, instance, board, signed-in account
+\`\`\`
+
+Pick a board with \`-b <label>\` (defaults to \`main\`), or bypass config with
+\`--board-id <id>\`. Canonical lists on a task board: \`Inbox\`, \`Todo\`, \`Doing\`,
+\`Review\`, \`Done\`.
+
+## Safety Rules
+
+- Never move a card to \`Done\` without verification.
+- This workflow uses \`Done\` \u2014 there is no separate "Complete" state.
+- Before development, inspect the **full** card: title, description, checklist,
+  labels, comments, images/attachments, artifacts, external refs, assignees,
+  custom data, and \`agent_meta\`.
+- Before changing a card, leave a comment that explains the plan.
+- Preserve user changes in the repo. Do not revert unrelated dirty files.
+- Scope remote writes to the resolved board (\`smash status\` to confirm).
+- If an operation can affect production data beyond the task board, ask first.
+
+## Command vocabulary
+
+MCP-first; the CLI equivalents are shown so the workflow is reproducible.
+
+\`\`\`bash
+smash status                     # resolved config / instance / board / account
+smash read                       # show the board (lists + cards)
+smash scan --list "Todo"         # actionable cards as JSON (best for agents)
+smash create "Fix signup bug"    # add a card to the resolved board (--list to target)
+smash move <cardId> "Review"     # move a card to a list by name
+smash archive <cardId>           # archive (soft-delete) a card
+
+smash card show <cardId>                       # full card detail before acting
+smash card update <cardId> --title/--desc ...  # edit fields
+smash comment add <cardId> "plan / progress"   # leave a comment
+smash checklist add <cardId> "step"            # checklist items
+smash agent-meta set <cardId> --data '{...}'   # structured agent state (see below)
+smash artifact create <cardId> --kind markdown --name "Report" --content-md-file ./r.md
+\`\`\`
+
+Use \`smash <group> --help\` for the full surface (\`board\`/\`list\`/\`card\`/
+\`comment\`/\`checklist\`/\`label\`/\`artifact\`/\`attachment\`/\`agent-meta\`/
+\`external-refs\`/\`assignees\`).
+
+## List matching
+
+Use exact canonical names when present. For Todo-like selection, match
+case-insensitively and semantically: \`Todo\`, \`To Do\`, \`\u3084\u308B\u3053\u3068\`, \`\u3084\u308B\`,
+\`\u30BF\u30B9\u30AF\`, \`Backlog\`, \`Next\`, \`Ready\`, \`Planned\`. Exclude \`Doing\`, \`Review\`,
+\`Done\`, and archive-like lists unless the user explicitly asks.
+
+## \`agent_meta\` convention
+
+Keep the card's agent state current while you work:
+
+\`\`\`json
+{
+  "primary_agent": "claude-code",   // or "codex"
+  "status": "working",              // working | waiting_review | done
+  "turn": "agent",                  // agent | human
+  "current_step": "concise phase",
+  "progress": 0.4                   // realistic partial value
+}
+\`\`\`
+
+Set \`status: "done"\` only after verification passes.
+
+## Command: /smash list
+
+Show the current board state before choosing work. Do **not** mutate.
+
+1. Read the resolved board (\`smash read\`, or \`smash scan\` for JSON).
+2. Report board title, board ID, each list (name, ID, card count), and active
+   card titles, kept compact.
+
+Infer options from wording: \`brief\` (names + counts), \`full\` (all cards incl.
+Done), \`todo\` / \`review\` / \`inbox\` (that list only), \`ids\` (include IDs).
+
+## Command: /smash inbox
+
+Research the board and create actionable improvement cards in \`Inbox\`.
+
+1. Read the current board to avoid duplicates.
+2. Generate concrete ideas from multiple perspectives (entrepreneur, UI/UX,
+   engineer, AI specialist).
+3. For each, create one \`Inbox\` card with a specific title, a detailed
+   description (user value, expected behavior, acceptance criteria), and an
+   optional checklist. Add a short comment naming the perspective and rationale.
+
+Quality bar: titles must be concrete and implementable; no vague cards like
+"Improve UI"; avoid duplicating existing cards.
+
+## Command: /smash todo-dig
+
+Deeply analyze Todo-like cards and prepare them for implementation.
+
+1. Find Todo-like lists (see list matching).
+2. Inspect all card data (\`smash card show <cardId>\`).
+3. Comment the implementation approach, likely files/modules, risks, unknowns,
+   and validation plan.
+4. Update \`agent_meta\` (\`status: working\`, \`turn: agent\`, \`progress: ~0.2\`).
+5. Create/update a checklist with implementation and verification steps.
+6. Do not move cards unless asked.
+
+Run cards in parallel only when implementation areas do not overlap.
+
+## Command: /smash todo-dev
+
+Implement Todo-like cards end to end.
+
+1. Find Todo-like lists; inspect the full card.
+2. Comment the implementation approach **before editing code**.
+3. Move the card to \`Doing\` (\`smash move <cardId> "Doing"\`).
+4. Update \`agent_meta\` (\`status: working\`, \`progress\` starting near \`0.1\`).
+5. Implement the change in the repo.
+6. Run appropriate checks: \`npm run build\`; unit/API/contract tests when
+   relevant; a dev-browser/UI check for UI changes.
+7. Update checklist items as completed.
+8. Add a completion comment with changed files and verification results.
+9. Move to \`Review\` \u2014 **not** \`Done\` \u2014 unless /smash review has already verified.
+
+Use subagents only for independent work with disjoint file ownership.
+
+## Command: /smash review
+
+Verify \`Review\` cards and move verified work to \`Done\`.
+
+1. Inspect the card; understand what must be verified.
+2. Choose verification: UI change \u2192 run the app/dev-browser; logic/API change \u2192
+   unit/integration/API tests; broad change \u2192 \`npm run build\` + targeted tests.
+3. Inspect screenshots or test output.
+4. On pass: comment the verification command/result, move \`Review\` \u2192 \`Done\`, set
+   \`agent_meta.status: done\`.
+5. On fail: keep in \`Review\` or move back to \`Doing\`, comment the failure and the
+   next action.
+
+## Fallbacks
+
+- Prefer \`smashspace-mcp\` MCP tools. If unavailable, use the \`smash\` CLI.
+- If the CLI is not installed: \`npm i -g smashspace\`, then \`smash login\`.
+- If a board returns "Sign-in required": run \`smash login\`, or set \`SMASH_TOKEN\`
+  for a headless/CI agent.
+
+## Required Final Report
+
+At the end of any /smash workflow, report:
+
+- board and list(s) touched
+- cards created, moved, or updated
+- comments / checklists / custom data / \`agent_meta\` changes
+- verification commands and results
+- any cards left blocked or unverified
+`;
+var OPENAI_AGENT_YAML = `interface:
+  display_name: "SmashSpace Operator"
+  short_description: "Run SmashSpace task-board workflows."
+  default_prompt: "Use $smash to run /smash review on the resolved board."
+`;
+function smashspaceJson(baseUrl, boardId) {
+  return `${JSON.stringify(
+    {
+      base_url: baseUrl,
+      default: "main",
+      spaces: {
+        main: { space_id: boardId, comment: "Team task board" }
+      }
+    },
+    null,
+    2
+  )}
+`;
+}
+function mcpServerEntry(baseUrl, boardId) {
+  return {
+    command: "smashspace-mcp",
+    env: {
+      SMASH_BASE_URL: baseUrl,
+      SMASH_SPACES: `${baseUrl.replace(/\/+$/, "")}/space/${boardId}`
+    }
+  };
+}
+
 // ../../cli/index.ts
 var DEFAULT_BASE_URL = process.env.SMASH_BASE_URL ?? "https://smashspace.app";
 var program2 = new Command();
@@ -4479,6 +4692,90 @@ program2.command("status").aliases(["context", "where"]).description(
   }
   show(void 0, lines);
 });
+program2.command("init").description(
+  "Scaffold this project for agents: operator skill + .smashspace.json + .mcp.json"
+).option("--board-id <id>", "Board/space id to pin in .smashspace.json / .mcp.json").option("--skills-only", "Only (re)install the operator skill files").option("--no-mcp", "Skip writing .mcp.json").option("-f, --force", "Overwrite .smashspace.json / .mcp.json if they exist").action(
+  async (opts) => {
+    const cwd = process.cwd();
+    const actions = [];
+    const abs = (rel) => join3(cwd, rel);
+    const put = async (rel, content) => {
+      const p = abs(rel);
+      await mkdir2(dirname3(p), { recursive: true });
+      await writeFile2(p, content, "utf8");
+    };
+    const exists = async (rel) => {
+      try {
+        await readFile2(abs(rel));
+        return true;
+      } catch {
+        return false;
+      }
+    };
+    await put(".claude/skills/smash/SKILL.md", SMASH_SKILL_MD);
+    await put(".codex/skills/smash/SKILL.md", SMASH_SKILL_MD);
+    await put(".codex/skills/smash/agents/openai.yaml", OPENAI_AGENT_YAML);
+    actions.push(
+      "\u2713 operator skill \u2192 .claude/skills/smash/ + .codex/skills/smash/"
+    );
+    const baseUrl = resolveBaseUrl();
+    const boardId = opts.boardId ?? "b_xxxxxxxx";
+    const placeholder = boardId === "b_xxxxxxxx";
+    if (!opts.skillsOnly) {
+      if (await exists(CONFIG_FILENAME) && !opts.force) {
+        actions.push(`\u2022 ${CONFIG_FILENAME} exists \u2014 kept (use --force)`);
+      } else {
+        await put(CONFIG_FILENAME, smashspaceJson(baseUrl, boardId));
+        actions.push(
+          `\u2713 ${CONFIG_FILENAME}${placeholder ? " (placeholder space_id \u2014 edit it)" : ` (${boardId})`}`
+        );
+      }
+      if (opts.mcp !== false) {
+        let mcp = { mcpServers: {} };
+        let parseFailed = false;
+        if (await exists(".mcp.json")) {
+          try {
+            const parsed = JSON.parse(await readFile2(abs(".mcp.json"), "utf8"));
+            if (parsed && typeof parsed === "object")
+              mcp = parsed;
+          } catch {
+            parseFailed = true;
+          }
+          if (!mcp.mcpServers || typeof mcp.mcpServers !== "object") {
+            mcp.mcpServers = {};
+          }
+        }
+        if (parseFailed && !opts.force) {
+          actions.push(
+            "\u26A0 .mcp.json exists but is not valid JSON \u2014 left untouched; add the 'smashspace' server by hand or re-run with --force"
+          );
+        } else {
+          const servers = mcp.mcpServers;
+          if (servers.smashspace && !opts.force) {
+            actions.push("\u2022 .mcp.json already wires 'smashspace' \u2014 kept (use --force)");
+          } else {
+            servers.smashspace = mcpServerEntry(baseUrl, boardId);
+            await put(".mcp.json", `${JSON.stringify(mcp, null, 2)}
+`);
+            actions.push("\u2713 .mcp.json \u2014 smashspace MCP server");
+          }
+        }
+      }
+    }
+    const next = ["", "Next:", "  1. smash login              # sign in (browser approval)"];
+    if (!opts.skillsOnly && placeholder) {
+      next.push("  2. edit .smashspace.json    # set your real space_id (`smash board list` to find it)");
+    }
+    next.push(
+      "  \u2192 Claude Code / Codex pick up .claude|.codex/skills/smash automatically"
+    );
+    if (getOpts().json) {
+      show({ cwd, actions, baseUrl, boardId: placeholder ? null : boardId });
+      return;
+    }
+    show(void 0, [...actions, ...next]);
+  }
+);
 program2.command("create <title>").description(`Create a card on the resolved board (${CONFIG_FILENAME}, default "main")`).option("-b, --board <label>", "board label from config").option("--board-id <id>", "explicit board id (bypass config)").option("-l, --list <name>", "target list name (default: first list)").option("-d, --desc <text>", "card description (Markdown)").action(async (title, opts) => {
   const ctx = resolveContext(opts);
   const detail = await fetchBoard(ctx.boardId, ctx.baseUrl);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "smashspace",
-  "version": "0.1.2",
+  "version": "0.1.4",
   "description": "SmashSpace CLI + MCP — operate SmashSpace boards from your terminal, Claude Code, Cursor, and Codex.",
   "type": "module",
   "bin": {