tuncss-plan-kit 0.1.0

package/.opencode/plugins/tuncss-plan-kit.js

@@ -0,0 +1,43 @@
+import path from "path";
+import { fileURLToPath } from "url";
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const skillsDir = path.resolve(__dirname, "../../skills");
+
+const WRAPPERS = {
+  brainstorm: {
+    description: "Turn an idea into an approved spec",
+    template:
+      "Use the `brainstorm` skill to handle the following request:\n\n$ARGUMENTS\n",
+  },
+  "plan-universal": {
+    description: "Turn an approved spec into an executable implementation plan",
+    template:
+      "Use the `plan-universal` skill to handle the following request:\n\n$ARGUMENTS\n",
+  },
+  "handoff-plan": {
+    description:
+      "Generate a paste-ready handoff message for another LLM agent to execute the plan",
+    template:
+      "Use the `handoff-plan` skill to handle the following request:\n\n$ARGUMENTS\n",
+  },
+};
+
+export const TuncssPlanKitPlugin = async () => ({
+  config: async (config) => {
+    config.skills = config.skills || {};
+    config.skills.paths = config.skills.paths || [];
+    if (!config.skills.paths.includes(skillsDir)) {
+      config.skills.paths.push(skillsDir);
+    }
+    config.command = config.command || {};
+    for (const [name, def] of Object.entries(WRAPPERS)) {
+      if (!config.command[name]) {
+        config.command[name] = {
+          template: def.template,
+          description: def.description,
+        };
+      }
+    }
+  },
+});

package/README.md

@@ -0,0 +1,113 @@
+# tuncss-plan-kit
+
+Three skills for spec-driven development, installable into Claude Code, Codex CLI, and OpenCode:
+
+- **`/brainstorm`** — turn an idea into an approved spec (`docs/specs/`)
+- **`/plan-universal`** — turn a spec into an executable plan (`docs/plans/`)
+- **`/handoff-plan`** — generate a paste-ready briefing for another LLM agent to execute the plan (`docs/handoffs/`)
+
+No agents, no routing, no TDD ceremony. Just three skills that get you from idea → spec → plan → handoff.
+
+## Install
+
+In your project directory:
+
+```bash
+npx tuncss-plan-kit init
+```
+
+The installer auto-detects which platform(s) the project uses and writes the right files.
+
+| Detected | Means |
+|---|---|
+| `.claude/` or `CLAUDE.md` | Claude Code |
+| `.codex/` | Codex CLI |
+| `.opencode/` | OpenCode |
+| `AGENTS.md` (alone) | Both Codex and OpenCode (they share `AGENTS.md`) |
+
+If nothing is detected, pass an explicit target:
+
+```bash
+npx tuncss-plan-kit init --target=claude
+npx tuncss-plan-kit init --target=claude,codex
+npx tuncss-plan-kit init --target=all
+```
+
+Re-running is safe. Skill and command files are overwritten only with `--force`. Instruction-file marker blocks are always replaced in place — your other content survives.
+
+Restart your coding agent after install so it picks up the new skills and slash commands.
+
+## What gets written where
+
+| Platform | Skills | Commands | Instructions |
+|---|---|---|---|
+| Claude Code | `.claude/skills/<n>/SKILL.md` | *(none — skills auto-expose as slash)* | `CLAUDE.md` |
+| Codex CLI | `.agents/skills/<n>/SKILL.md` | `.codex/prompts/<n>.md` | `AGENTS.md` |
+| OpenCode | `.opencode/skills/<n>/SKILL.md` | `.opencode/commands/<n>.md` | `AGENTS.md` |
+
+Claude Code automatically exposes any skill named `foo` as `/foo`, so the kit doesn't write wrapper command files for it. Codex and OpenCode don't auto-expose, so wrappers are written there to give you the same `/brainstorm`, `/plan-universal`, `/handoff-plan` UX everywhere.
+
+With `--global` the same files go to user-wide locations (`~/.claude/`, `~/.agents/`, `~/.codex/`).
+
+**OpenCode `--global` is supported via an npm-plugin route**: the kit installs itself into `~/.config/opencode/node_modules/`, registers itself in `~/.config/opencode/opencode.json`'s `plugin` array, and drops command wrappers into `~/.config/opencode/commands/`. After install, restart OpenCode — skills appear in every project. (For Claude and Codex, `--global` is a plain file copy.)
+
+Project-local is still the default for all three — recommended unless you specifically want the kit available everywhere.
+
+## Workflow
+
+```
+You:     /brainstorm I want a CLI that ...
+Agent:   ↓ brainstorming skill
+         asks one question at a time, proposes 2-3 approaches, presents
+         the design section by section, writes spec to docs/specs/
+You:     (review and approve)
+
+You:     /plan-universal
+Agent:   ↓ writing-plans skill
+         writes plan to docs/plans/ with execution contract at the top,
+         tasks shaped as Targets / Model Tier / Implementation Notes /
+         Done When / Verification
+
+You:     do TASK-01
+Agent:   reads only TASK-01's block, stays inside its Targets, stops for
+         approval when done
+
+— or —
+
+You:     /handoff-plan
+Agent:   ↓ handoff skill
+         writes a short briefing to docs/handoffs/ that you can paste
+         into another agent (or feed it the file path)
+```
+
+## What's in a plan
+
+Every plan starts with this contract:
+
+> 1. Read **only** that task's block. Do not preview other tasks.
+> 2. Stay strictly inside its **Targets** — do not edit files outside that list.
+> 3. Follow the **Implementation Notes**; do not invent extra scope.
+> 4. When **Done When** and **Verification** are satisfied, **stop and report**. Wait for approval.
+> 5. If verification fails, report and stop. Do not attempt fixes outside the task's Targets.
+
+Tasks are tagged with model tiers (T1 Fast / T2 Balanced / T3 Power / T4 Reasoning) so you can route execution to the cheapest model that can do the job.
+
+## Options
+
+```
+npx tuncss-plan-kit init [--target=<list>] [--global] [--force]
+```
+
+| Flag | Effect |
+|------|--------|
+| `--target=<list>` | Comma-separated. Values: `claude`, `codex`, `opencode`, `all`. Auto-detected if omitted. |
+| `--global` | Install to user-wide locations instead of the current project. |
+| `--force` | Overwrite existing skill/command files without warning. |
+
+## Why this exists
+
+Existing kits ship dozens of agents and skills you'll never use, but every one of them sits in your context and burns tokens each turn. `tuncss-plan-kit` ships three files that cover the only loop most projects need: design → plan → execute (here or elsewhere). That's it.
+
+## License
+
+MIT

package/bin/cli.js

@@ -0,0 +1,426 @@
+#!/usr/bin/env node
+
+import fs from "fs";
+import path from "path";
+import os from "os";
+import { spawnSync } from "child_process";
+import { fileURLToPath } from "url";
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const PKG_ROOT = path.resolve(__dirname, "..");
+const PKG_NAME = "tuncss-plan-kit";
+
+const SKILLS = ["brainstorm", "plan-universal", "handoff-plan"];
+const COMMANDS = ["brainstorm", "plan-universal", "handoff-plan"];
+const MARKER_START = "<!-- tuncss-plan-kit:start -->";
+const MARKER_END = "<!-- tuncss-plan-kit:end -->";
+
+const PLATFORMS = {
+  claude: {
+    label: "claude",
+    project: {
+      skillsDir: ".claude/skills",
+      commandsDir: null,
+      instructionsFile: "CLAUDE.md",
+    },
+    global: (home) => ({
+      skillsDir: path.join(home, ".claude", "skills"),
+      commandsDir: null,
+      instructionsFile: path.join(home, ".claude", "CLAUDE.md"),
+    }),
+    commandsSrc: null,
+    skipCommands: true,
+  },
+  codex: {
+    label: "codex",
+    project: {
+      skillsDir: ".agents/skills",
+      commandsDir: ".codex/prompts",
+      instructionsFile: "AGENTS.md",
+    },
+    global: (home) => ({
+      skillsDir: path.join(home, ".agents", "skills"),
+      commandsDir: path.join(home, ".codex", "prompts"),
+      instructionsFile: path.join(home, ".codex", "AGENTS.md"),
+    }),
+    commandsSrc: "codex",
+  },
+  opencode: {
+    label: "opencode",
+    project: {
+      skillsDir: ".opencode/skills",
+      commandsDir: ".opencode/commands",
+      instructionsFile: "AGENTS.md",
+    },
+    // Global install for OpenCode uses the npm-plugin route, not file-drop.
+    // See installOpenCodeGlobal().
+    global: null,
+    commandsSrc: "opencode",
+  },
+};
+
+const SUPPORTED = Object.keys(PLATFORMS);
+
+function parseArgs(argv) {
+  const args = { command: null, target: null, global: false, force: false };
+  for (const a of argv) {
+    if (!args.command && !a.startsWith("--")) {
+      args.command = a;
+    } else if (a.startsWith("--target=")) {
+      args.target = a
+        .slice("--target=".length)
+        .split(",")
+        .map((s) => s.trim())
+        .filter(Boolean);
+    } else if (a === "--global") {
+      args.global = true;
+    } else if (a === "--force") {
+      args.force = true;
+    } else if (a === "--help" || a === "-h") {
+      args.command = "help";
+    }
+  }
+  return args;
+}
+
+function printHelp() {
+  console.log(`tuncss-plan-kit
+
+Usage:
+  npx tuncss-plan-kit init [--target=<list>] [--global] [--force]
+
+Commands:
+  init      Install the three skills (brainstorm, plan-universal, handoff-plan)
+            into the target platform(s).
+
+Options:
+  --target  Comma-separated platforms to install for. Supported:
+              claude, codex, opencode, all
+            If omitted, auto-detects from the current directory.
+  --global  Install to user-wide locations.
+            For OpenCode this uses the npm-plugin route (installs the package
+            into ~/.config/opencode/node_modules/ and registers it in
+            opencode.json's plugin array).
+  --force   Overwrite existing skill/command files without warning.
+            (Instruction-file marker blocks are always idempotent.)
+
+Examples:
+  npx tuncss-plan-kit init
+  npx tuncss-plan-kit init --target=claude
+  npx tuncss-plan-kit init --target=claude,codex
+  npx tuncss-plan-kit init --target=all --global
+`);
+}
+
+function exists(p) {
+  try {
+    fs.accessSync(p);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function detectTargets(cwd) {
+  const found = new Set();
+  if (exists(path.join(cwd, ".claude")) || exists(path.join(cwd, "CLAUDE.md"))) {
+    found.add("claude");
+  }
+  if (exists(path.join(cwd, ".codex"))) found.add("codex");
+  if (exists(path.join(cwd, ".opencode"))) found.add("opencode");
+  if (exists(path.join(cwd, "AGENTS.md"))) {
+    if (!found.has("codex") && !found.has("opencode")) {
+      found.add("codex");
+      found.add("opencode");
+    }
+  }
+  return [...found];
+}
+
+function ensureDir(dir) {
+  fs.mkdirSync(dir, { recursive: true });
+}
+
+function copyFile(src, dest, force) {
+  if (exists(dest) && !force) {
+    const a = fs.readFileSync(src, "utf8");
+    const b = fs.readFileSync(dest, "utf8");
+    if (a === b) return { status: "unchanged", dest };
+    fs.writeFileSync(dest, a);
+    return { status: "updated", dest };
+  }
+  ensureDir(path.dirname(dest));
+  fs.writeFileSync(dest, fs.readFileSync(src, "utf8"));
+  return { status: "written", dest };
+}
+
+function escapeRegex(s) {
+  return s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+
+function upsertMarkerBlock(filePath, blockBody) {
+  const block = `${MARKER_START}\n${blockBody.trim()}\n${MARKER_END}`;
+  let existing = "";
+  if (exists(filePath)) existing = fs.readFileSync(filePath, "utf8");
+  if (existing.includes(MARKER_START) && existing.includes(MARKER_END)) {
+    const re = new RegExp(
+      `${escapeRegex(MARKER_START)}[\\s\\S]*?${escapeRegex(MARKER_END)}`,
+      "m"
+    );
+    const next = existing.replace(re, block);
+    if (next === existing) return { status: "unchanged" };
+    ensureDir(path.dirname(filePath));
+    fs.writeFileSync(filePath, next);
+    return { status: "block-updated" };
+  }
+  const sep =
+    existing.length === 0 ? "" : existing.endsWith("\n") ? "\n" : "\n\n";
+  ensureDir(path.dirname(filePath));
+  fs.writeFileSync(filePath, existing + sep + block + "\n");
+  return { status: existing.length === 0 ? "file-created" : "block-appended" };
+}
+
+function loadInstructionsBlock() {
+  const tplPath = path.join(PKG_ROOT, "templates", "instructions-block.md");
+  const tpl = fs.readFileSync(tplPath, "utf8");
+  return tpl.replace(MARKER_START, "").replace(MARKER_END, "").trim();
+}
+
+function relPath(p, base) {
+  const r = path.relative(base, p);
+  return r.split(path.sep).join("/");
+}
+
+function statusTag(status) {
+  if (status === "unchanged") return "·";
+  if (status === "updated" || status === "block-updated") return "↻";
+  return "✓";
+}
+
+function installPlatform({ platform, isGlobal, force, baseRoot, sharedState }) {
+  const cfg = PLATFORMS[platform];
+  const paths = isGlobal
+    ? cfg.global(os.homedir())
+    : {
+        skillsDir: path.join(baseRoot, cfg.project.skillsDir),
+        commandsDir: cfg.project.commandsDir
+          ? path.join(baseRoot, cfg.project.commandsDir)
+          : null,
+        instructionsFile: path.join(baseRoot, cfg.project.instructionsFile),
+      };
+  const displayBase = isGlobal ? os.homedir() : baseRoot;
+
+  const lines = [];
+
+  for (const skill of SKILLS) {
+    const src = path.join(PKG_ROOT, "skills", skill, "SKILL.md");
+    const dest = path.join(paths.skillsDir, skill, "SKILL.md");
+    const r = copyFile(src, dest, force);
+    lines.push(`  ${statusTag(r.status)} ${relPath(r.dest, displayBase)}`);
+  }
+
+  if (!cfg.skipCommands) {
+    for (const cmd of COMMANDS) {
+      const src = path.join(PKG_ROOT, "commands", cfg.commandsSrc, `${cmd}.md`);
+      const dest = path.join(paths.commandsDir, `${cmd}.md`);
+      const r = copyFile(src, dest, force);
+      lines.push(`  ${statusTag(r.status)} ${relPath(r.dest, displayBase)}`);
+    }
+  } else {
+    lines.push(
+      `  · (skill names auto-expose as slash commands; no wrapper files needed)`
+    );
+  }
+
+  if (sharedState.writtenInstructionFiles.has(paths.instructionsFile)) {
+    lines.push(
+      `  · ${relPath(paths.instructionsFile, displayBase)} (already updated this run)`
+    );
+  } else {
+    const r = upsertMarkerBlock(
+      paths.instructionsFile,
+      sharedState.instructionsBlock
+    );
+    sharedState.writtenInstructionFiles.add(paths.instructionsFile);
+    lines.push(
+      `  ${statusTag(r.status)} ${relPath(paths.instructionsFile, displayBase)} (${r.status})`
+    );
+  }
+
+  return lines;
+}
+
+function readJsonOrDefault(filePath, fallback) {
+  if (!exists(filePath)) return fallback;
+  try {
+    return JSON.parse(fs.readFileSync(filePath, "utf8"));
+  } catch {
+    return fallback;
+  }
+}
+
+function writeJson(filePath, obj) {
+  ensureDir(path.dirname(filePath));
+  fs.writeFileSync(filePath, JSON.stringify(obj, null, 2) + "\n");
+}
+
+function isRunningFromInstalledPackage() {
+  // If our package root contains /node_modules/, we were installed as a dep
+  // (e.g. via `npm install -g` or `npx`). Otherwise we're being run from
+  // source (dev mode).
+  return PKG_ROOT.split(path.sep).includes("node_modules");
+}
+
+function dependencySpec() {
+  // When running from a published install, use a version range so npm
+  // installs from the registry. When running from source (dev), point to
+  // our absolute path with file: so changes are picked up without publish.
+  if (isRunningFromInstalledPackage()) {
+    return `^${readJsonOrDefault(path.join(PKG_ROOT, "package.json"), { version: "0.1.0" }).version || "0.1.0"}`;
+  }
+  return "file:" + PKG_ROOT.split(path.sep).join("/");
+}
+
+function installOpenCodeGlobal() {
+  const home = os.homedir();
+  const ocDir = path.join(home, ".config", "opencode");
+  ensureDir(ocDir);
+  const lines = [];
+
+  // 1. package.json — add or update tuncss-plan-kit dependency
+  const pkgPath = path.join(ocDir, "package.json");
+  const pkg = readJsonOrDefault(pkgPath, {});
+  pkg.dependencies = pkg.dependencies || {};
+  const spec = dependencySpec();
+  const prevSpec = pkg.dependencies[PKG_NAME];
+  pkg.dependencies[PKG_NAME] = spec;
+  writeJson(pkgPath, pkg);
+  lines.push(
+    `  ${prevSpec === spec ? "·" : prevSpec ? "↻" : "✓"} ${relPath(pkgPath, home)} (dep: ${PKG_NAME}@${spec})`
+  );
+
+  // 2. npm install in ocDir
+  const npmCmd = process.platform === "win32" ? "npm.cmd" : "npm";
+  const npmRes = spawnSync(npmCmd, ["install", "--silent", "--no-audit", "--no-fund"], {
+    cwd: ocDir,
+    stdio: "inherit",
+    shell: process.platform === "win32",
+  });
+  if (npmRes.status !== 0) {
+    throw new Error(
+      `npm install failed in ${ocDir} (exit code ${npmRes.status}). Fix the error above and re-run.`
+    );
+  }
+  lines.push(`  ✓ npm install ran in ${relPath(ocDir, home)}`);
+
+  // 3. command wrappers — file-drop into ~/.config/opencode/commands/
+  // (the plugin handles skills via config injection, but command discovery
+  // appears to require file-drop)
+  const cmdDir = path.join(ocDir, "commands");
+  for (const cmd of COMMANDS) {
+    const src = path.join(PKG_ROOT, "commands", "opencode", `${cmd}.md`);
+    const dest = path.join(cmdDir, `${cmd}.md`);
+    const r = copyFile(src, dest, false);
+    lines.push(`  ${statusTag(r.status)} ${relPath(r.dest, home)}`);
+  }
+
+  // 4. opencode.json — add plugin reference (idempotent)
+  const ocJsonPath = path.join(ocDir, "opencode.json");
+  const ocJson = readJsonOrDefault(ocJsonPath, {
+    $schema: "https://opencode.ai/config.json",
+  });
+  ocJson.plugin = ocJson.plugin || [];
+  // Normalize to strings only (we don't use the [string, object] tuple form)
+  const pluginPath = `~/.config/opencode/node_modules/${PKG_NAME}`;
+  const alreadyHas = ocJson.plugin.some(
+    (p) => p === pluginPath || (Array.isArray(p) && p[0] === pluginPath)
+  );
+  if (!alreadyHas) {
+    ocJson.plugin.push(pluginPath);
+  }
+  writeJson(ocJsonPath, ocJson);
+  lines.push(
+    `  ${alreadyHas ? "·" : "✓"} ${relPath(ocJsonPath, home)} (plugin: ${pluginPath})`
+  );
+
+  return lines;
+}
+
+function init(args) {
+  const cwd = process.cwd();
+
+  let targets = args.target;
+  if (targets && targets.includes("all")) {
+    targets = SUPPORTED.slice();
+  }
+  if (!targets) {
+    targets = detectTargets(cwd);
+    if (targets.length === 0) {
+      console.error(
+        "No supported platform detected in this directory.\n" +
+          "Specify one explicitly, e.g.: npx tuncss-plan-kit init --target=claude\n" +
+          "Or install for all three: npx tuncss-plan-kit init --target=all"
+      );
+      process.exit(1);
+    }
+  }
+
+  const unsupported = targets.filter((t) => !SUPPORTED.includes(t));
+  if (unsupported.length > 0) {
+    console.error(
+      `Unsupported target(s): ${unsupported.join(", ")}.\n` +
+        `Supported: ${SUPPORTED.join(", ")}, all.`
+    );
+    process.exit(1);
+  }
+
+  targets = SUPPORTED.filter((p) => targets.includes(p));
+
+  console.log(`tuncss-plan-kit init`);
+  console.log(`  scope:  ${args.global ? "global (user-wide)" : "project (./)"}`);
+  console.log(`  target: ${targets.join(", ")}`);
+  console.log("");
+
+  const sharedState = {
+    instructionsBlock: loadInstructionsBlock(),
+    writtenInstructionFiles: new Set(),
+  };
+
+  for (const platform of targets) {
+    console.log(`[${platform}]`);
+    if (platform === "opencode" && args.global) {
+      const lines = installOpenCodeGlobal();
+      for (const l of lines) console.log(l);
+    } else {
+      const lines = installPlatform({
+        platform,
+        isGlobal: args.global,
+        force: args.force,
+        baseRoot: cwd,
+        sharedState,
+      });
+      for (const l of lines) console.log(l);
+    }
+    console.log("");
+  }
+
+  console.log(
+    "Done. Restart your coding agent(s) to pick up new skills and slash commands."
+  );
+}
+
+function main() {
+  const args = parseArgs(process.argv.slice(2));
+  if (!args.command || args.command === "help") {
+    printHelp();
+    process.exit(args.command ? 0 : 1);
+  }
+  if (args.command === "init") {
+    return init(args);
+  }
+  console.error(`Unknown command: ${args.command}`);
+  printHelp();
+  process.exit(1);
+}
+
+main();

package/commands/codex/brainstorm.md

@@ -0,0 +1 @@
+Use the `brainstorm` skill to handle the user's request.

package/commands/codex/handoff-plan.md

@@ -0,0 +1 @@
+Use the `handoff-plan` skill to handle the user's request.

package/commands/codex/plan-universal.md

@@ -0,0 +1 @@
+Use the `plan-universal` skill to handle the user's request.

package/commands/opencode/brainstorm.md

@@ -0,0 +1,7 @@
+---
+description: Turn an idea into an approved spec
+---
+
+Use the `brainstorm` skill to handle the following request:
+
+$ARGUMENTS

package/commands/opencode/handoff-plan.md

@@ -0,0 +1,7 @@
+---
+description: Generate a paste-ready handoff message for another LLM agent to execute the plan
+---
+
+Use the `handoff-plan` skill to handle the following request:
+
+$ARGUMENTS

package/commands/opencode/plan-universal.md

@@ -0,0 +1,7 @@
+---
+description: Turn an approved spec into an executable implementation plan
+---
+
+Use the `plan-universal` skill to handle the following request:
+
+$ARGUMENTS

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "tuncss-plan-kit",
+  "version": "0.1.0",
+  "type": "module",
+  "main": ".opencode/plugins/tuncss-plan-kit.js",
+  "description": "Three-skill kit for spec-driven development: brainstorm an idea into a spec, turn the spec into an executable plan, hand the plan off to another LLM agent.",
+  "bin": {
+    "tuncss-plan-kit": "bin/cli.js"
+  },
+  "files": [
+    "bin/",
+    "skills/",
+    "commands/",
+    "templates/",
+    ".opencode/",
+    "README.md"
+  ],
+  "keywords": [
+    "claude-code",
+    "claude",
+    "skills",
+    "brainstorming",
+    "planning",
+    "spec-driven",
+    "llm-agents"
+  ],
+  "author": "tuncss",
+  "license": "MIT",
+  "engines": {
+    "node": ">=18"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/tuncss/tuncss-plan-kit"
+  }
+}

package/skills/brainstorm/SKILL.md

@@ -0,0 +1,132 @@
+---
+name: brainstorm
+description: Use before any feature, component, or behavior change. Turns an idea into an approved design before any code is written.
+---
+
+# Brainstorming
+
+Turn an idea into a design the user approves, then hand off to plan-universal. No code, no scaffolding, no implementation skill until the design is approved.
+
+<HARD-GATE>
+Do NOT write code, scaffold, edit files for the feature, or invoke an implementation skill until you have presented a design and the user has approved it. This applies to every project regardless of size.
+</HARD-GATE>
+
+## "This is too simple to need a design"
+
+It isn't. A todo list, a one-file utility, a config tweak — all go through this. Simple-looking projects are where unexamined assumptions cost the most rework. The design can be three sentences for a trivial change. You still present it, you still get approval.
+
+## Checklist
+
+Work through these in order. Don't skip ahead.
+
+1. Explore project context — relevant files, recent commits, any existing docs
+2. Assess scope — if the request is actually several independent projects, decompose before going deeper
+3. Ask clarifying questions — one per message, multiple-choice when you can
+4. Propose 2-3 approaches — trade-offs and your recommendation
+5. Present the design section by section, getting approval after each
+6. Write the spec to `docs/specs/YYYY-MM-DD-<topic>-design.md`
+7. Self-review the spec — placeholders, contradictions, ambiguity, scope
+8. Wait for the user to review the written spec
+9. Hand off — ask the user to run `/plan-universal` (or implement directly only if trivial; see Hand-off)
+
+## Scope assessment
+
+Before any clarifying questions, look at the request as a whole. If it describes multiple independent subsystems ("a platform with chat, billing, file storage, and analytics"), don't refine details — that's wasted effort on something that needs to be decomposed first.
+
+When the request is too large for a single spec:
+- Name the independent pieces and how they relate
+- Suggest a build order
+- Brainstorm only the first sub-project through this flow
+- Each sub-project gets its own spec → plan → implementation cycle
+
+## Asking clarifying questions
+
+- One question per message. If a topic needs more, break it into multiple turns.
+- Prefer multiple-choice. Open-ended is fine when the space is genuinely open.
+- Focus on purpose, constraints, and what success looks like.
+- Don't ask about anything you can derive from reading the code.
+
+**If the user dumps answers in bulk** (numbered list answering several questions at once, or "just go ahead with X, Y, Z"), do NOT take it as permission to skip the gate. Acknowledge the answers, then ask 1-2 follow-ups on what those answers leave open — trade-offs, edge cases, or the next decision their choices imply ("LocalStorage confirmed — should we handle data clearing or schema versioning?"). Only move to approaches once those are resolved.
+
+## Proposing approaches
+
+Once you understand the goal, lay out 2-3 ways to solve it. Each gets its trade-offs in plain language. Lead with the one you'd pick and say why. Don't hide your recommendation behind false neutrality — but make it easy for the user to override.
+
+## Presenting the design
+
+Present in sections. Scale each section to its complexity:
+- A few sentences for something straightforward
+- Up to ~300 words when it's nuanced
+
+After each section, ask if it looks right before moving on. Cover what's actually relevant: architecture, components, data flow, error handling, testing. Skip what doesn't apply.
+
+If something doesn't fit together, go back and clarify. The point of these gates is to catch confusion before it lands in the spec.
+
+## Designing for isolation
+
+Break the system into small units that each have one purpose, talk to each other through clear interfaces, and can be understood and tested on their own.
+
+For each unit, you should be able to answer:
+- What does it do?
+- How do you use it?
+- What does it depend on?
+
+If a consumer has to read the internals to use a unit, the boundary is wrong. If you can't change internals without breaking consumers, the boundary is wrong. Smaller, well-bounded units are also easier to work with later — edits get more reliable when files are focused.
+
+## Working inside an existing codebase
+
+- Read the surrounding code first. Follow the patterns already there.
+- If existing code in the area has real problems that affect this work (an oversized file, tangled responsibilities, unclear boundaries), include the targeted improvement in the design — the way a careful developer cleans up the room they're working in.
+- Don't bundle unrelated refactoring. Stay on what serves the goal.
+
+## YAGNI
+
+Cut anything the request doesn't need yet. Future-proofing, config options "just in case", an abstraction for a hypothetical second consumer — all out, unless the user has actually named the second consumer.
+
+## Writing the spec
+
+After every section is approved, write the spec to `docs/specs/YYYY-MM-DD-<topic>-design.md` (override if the user has set a different location). Create `docs/specs/` if it doesn't exist. Commit the file.
+
+The spec is the document a future implementer reads. It captures decisions, not your reasoning trail. Keep it tight.
+
+## Spec self-review
+
+Re-read with fresh eyes. Fix issues inline; no second review pass.
+
+1. **Placeholders** — any "TBD", "TODO", or vague requirement? Resolve them.
+2. **Internal consistency** — do sections contradict each other? Does the architecture match the feature description?
+3. **Scope** — is this still a single implementation plan, or did it grow into something that needs decomposing?
+4. **Ambiguity** — could a requirement be read two different ways? Pick one and make it explicit.
+
+## User review gate
+
+After your self-review, ask the user to read the written spec:
+
+> Spec written and committed to `<path>`. Please review it and let me know if you want changes before we move to the implementation plan.
+
+Wait for their response. If they ask for changes, make them and re-run the self-review. Only move on once they approve.
+
+## Hand-off
+
+After the spec is approved, **do NOT start implementing**. The skill ends here. The next step is `/plan-universal`, which turns the spec into an executable plan with model-tier hints and per-task verification.
+
+End your final turn with this message to the user (paraphrase, but keep all four parts):
+
+> Spec is locked at `<path>`. Want me to write the implementation plan via `/plan-universal`? Or, if this is small enough — one file, no new public API, no schema or migration changes, no new dependency — say "implement directly" and I'll do it now.
+
+Then **stop and wait** for the user's choice. Default is `/plan-universal`. Implement directly **only** when:
+- The user explicitly says so (the phrase "implement directly" or equivalent)
+- **AND** the change meets every trivial criterion above
+
+If you find yourself thinking "the spec is small, I'll just knock it out" — that's the drift this gate exists to catch. Stop. Hand off.
+
+Do not invoke any other skill from this skill.
+
+## Key principles
+
+- One question at a time
+- Multiple choice when you can
+- YAGNI hard
+- Always explore 2-3 approaches before settling
+- Approve as you go — don't drop a wall of design and ask "thoughts?"
+- Be willing to back up when something doesn't fit

package/skills/handoff-plan/SKILL.md

@@ -0,0 +1,77 @@
+---
+name: handoff-plan
+description: Use after writing a plan when the user wants a short briefing message to paste into another LLM agent (Codex, Cursor, Copilot, etc.) so it can pick up execution. Triggered by /handoff-plan.
+---
+
+# Handoff Plan
+
+Produce a short, paste-ready briefing message that another LLM agent can use to pick up an existing plan in this repo. The receiving agent is assumed to have filesystem access — the message points at files rather than inlining them.
+
+**Announce at start:** "Generating handoff message."
+
+## Inputs
+
+- **If the user passes a plan path** (e.g. `/handoff-plan docs/plans/2026-05-13-foo.md`), use that file.
+- **Otherwise** pick the most recently modified `*.md` in `docs/plans/`. If `docs/plans/` doesn't exist or is empty, stop and tell the user to run `/plan-universal` first.
+
+If a spec matching the plan's slug exists in `docs/specs/`, include its path too. Best-effort match by filename slug; don't fabricate a path — omit the spec line if there's no clear match.
+
+## What to extract from the plan
+
+Read the plan file and pull:
+- **Goal** — the one-line goal from the header
+- **Tech / dependencies** — the tech line from the header
+- **Task list** — every `### TASK-NN: <name>` heading (just the numbers and names, not the bodies)
+
+## Repo context
+
+Get a one-line project descriptor:
+- Prefer `package.json` `name` + `description`
+- Fall back to the first non-empty line of `README.md`
+- One short sentence — no marketing language
+
+## Output
+
+Write the message to `docs/handoffs/YYYY-MM-DD-<feature-slug>.md` (date = today, slug = same slug as the plan file). Create `docs/handoffs/` if missing.
+
+After writing, print only a single confirmation line to chat:
+
+> Handoff written to `docs/handoffs/<filename>.md`.
+
+Do not echo the message contents — the user will open the file.
+
+## Message template
+
+````text
+You're picking up an implementation plan in this repo.
+
+**Project:** <project name> — <one-line description>
+
+**Plan:** `<path/to/plan.md>`
+**Spec:** `<path/to/spec.md>`   ← omit this line entirely if no spec found
+
+**Goal:** <goal line from plan>
+
+**Tech:** <tech line from plan>
+
+**Tasks:**
+- TASK-01: <name>
+- TASK-02: <name>
+- ...
+
+**How to execute (full execution contract is at the top of the plan file):**
+1. When I ask for a task ("do TASK-03"), read **only** that task's block in the plan.
+2. Stay strictly inside its **Targets** — don't edit files outside that list.
+3. Follow the **Implementation Notes**; don't invent extra scope.
+4. When **Done When** and **Verification** are satisfied, **stop and report**. Wait for my approval before moving on.
+5. If verification fails, report and stop. Don't attempt fixes outside the task's Targets.
+
+Start by reading `<plan path>` end-to-end, then wait for me to ask for the first task. Don't begin TASK-01 until I ask.
+````
+
+## Rules
+
+- Don't summarize task bodies. The receiving agent reads the plan file itself.
+- Don't reformat the execution contract beyond the 5 numbered rules above. They are the contract; the plan file is the source of truth.
+- Keep the message under ~50 lines. If you're tempted to add more context, you're inlining the plan — stop.
+- Don't include this skill's name, your model name, or any Claude-specific framing in the output. The receiver doesn't need to know how the message was generated.

package/skills/plan-universal/SKILL.md

@@ -0,0 +1,138 @@
+---
+name: plan-universal
+description: Use when you have an approved spec or a clear multi-step task and need to write the implementation plan before any code is written. Invoked via /plan-universal, usually after the brainstorm skill.
+---
+
+# Writing Plans
+
+Turn a spec into a plan an engineer can execute task by task without re-reading the spec. Assume they're capable but have zero context on this codebase or problem domain — every task must stand on its own.
+
+**Announce at start:** "Writing the implementation plan."
+
+**Save plans to:** `docs/plans/YYYY-MM-DD-<feature-name>.md` (override if the user has set a different location). Create `docs/plans/` if it doesn't exist.
+
+## Scope check
+
+If the spec covers multiple independent subsystems, that should have been caught during brainstorming. If it slipped through, stop and propose splitting it into one plan per subsystem before writing tasks. Each plan should produce working, testable software on its own.
+
+## File structure first
+
+Before defining tasks, map every file the plan will create or modify and what each is responsible for. Decomposition decisions get locked in here, not inside individual tasks.
+
+- One clear responsibility per file. Files that change together live together; split by responsibility, not technical layer.
+- Smaller, focused files are easier to edit reliably than large ones doing many things.
+- In an existing codebase, follow the patterns already there. If a file you're modifying has grown unwieldy and the work touches it heavily, including a focused split in the plan is reasonable. Don't bundle unrelated restructuring.
+
+This map is what makes the task list coherent. Each task should produce changes that make sense as a self-contained unit.
+
+## Plan document structure
+
+Every plan starts with this header:
+
+````markdown
+# <Feature Name> — Implementation Plan
+
+<!-- EXECUTION CONTRACT — read before touching any task -->
+> When the user asks for a specific task (e.g. "do TASK-03"):
+> 1. Read **only** that task's block. Do not preview other tasks.
+> 2. Stay strictly inside its **Targets** — do not edit files outside that list.
+> 3. Follow the **Implementation Notes**; do not invent extra scope.
+> 4. When **Done When** and **Verification** are satisfied, **stop and report**. Wait for approval before moving to the next task.
+> 5. If verification fails, report the failure and stop. Do not attempt fixes outside the task's Targets.
+
+**Goal:** <one sentence>
+
+**Architecture:** <2-3 sentences on the approach>
+
+**Tech / dependencies:** <key libraries, runtimes, services>
+
+**File map:**
+- `path/to/a.ts` — <responsibility>
+- `path/to/b.ts` — <responsibility>
+- `tests/...` — <what's covered, if anything>
+
+---
+````
+
+## Model tiers
+
+Every task gets a recommended tier. These are the cost/capability brackets for the model that should execute it:
+
+- **T1 — Fast:** trivial edits, renames, formatting, single-file boilerplate
+- **T2 — Balanced:** standard feature work in one component, contained logic
+- **T3 — Power:** multi-file changes, non-trivial logic, refactors with consequence
+- **T4 — Reasoning:** architecture decisions, gnarly debugging, cross-cutting design
+
+When in doubt, pick the lower tier. Upgrades are cheap; over-spending isn't.
+
+## Task structure
+
+Every task uses this shape:
+
+````markdown
+### TASK-01: <short name>
+
+**Targets:**
+- `exact/path/to/file.ts` (create | modify | delete)
+- `exact/path/to/other.ts` (modify)
+
+**Model Tier:** T2  <!-- T1 Fast | T2 Balanced | T3 Power | T4 Reasoning -->
+
+**Implementation Notes:**
+- What this task does, in plain language
+- Any non-obvious decision and why
+- Concrete code, types, function signatures, or commands the engineer needs — not "implement the handler" but the actual handler shape
+- If a public interface from an earlier task is consumed here, restate its signature; don't make the reader page back
+
+**Done When:**
+- Bullet list of observable outcomes
+- E.g. "endpoint returns 200 with `{ id, status }` body for valid input"
+- E.g. "type `Foo` exported from `src/foo.ts`"
+
+**Verification:**
+- Manual: <commands the engineer runs and what they should see>
+- Automated (optional): <test files, scripts, or `npm test -- foo` commands and expected output, only if automated coverage genuinely belongs here>
+````
+
+Tasks are self-contained because the executor reads exactly one block per turn (see the Execution Contract). If TASK-07 needs the shape of something defined in TASK-02, restate it in TASK-07 — don't make the reader scroll.
+
+## Granularity
+
+Each task should be a self-contained slice that produces something testable. Not microsteps like "write the failing test" / "make it pass" — that's noise. A task is roughly: a feature surface, a module, an endpoint, a screen, a migration. Split when:
+- Targets cross unrelated areas
+- The verification step would need multiple unrelated checks
+- The Implementation Notes start branching ("either X or Y depending on…")
+
+Merge when a task is so small it has no meaningful Done When of its own.
+
+## Tests are not mandatory
+
+Don't dictate TDD or per-task test coverage. Add Automated Verification only when an automated check genuinely belongs in that task (a regression test for a known-bug fix, a contract test for a new public API). For most tasks, **Done When** + Manual Verification is enough. Let the executor judge whether more coverage pays for itself.
+
+## No placeholders
+
+These are **plan failures**. Never write them:
+- "TBD", "TODO", "implement later", "fill in details"
+- "Add appropriate error handling" / "validate input" / "handle edge cases" — name the cases
+- "Write tests for the above" without the actual test names and what they assert
+- "Similar to TASK-N" — repeat what's needed; the executor reads tasks out of order
+- Steps that describe *what* without showing *how* — if a task changes code, show the code shape, the type, or the exact command
+- References to types, functions, or files not defined in any task or in the file map
+
+## Self-review
+
+After the plan is written, re-read it against the spec with fresh eyes. Fix issues inline; no second review pass.
+
+1. **Spec coverage** — go through each requirement in the spec. Can you point to the task that implements it? Add tasks for any gap.
+2. **Placeholder scan** — anything from the "No placeholders" list? Fix.
+3. **Name and type consistency** — a function called `clearLayers()` in TASK-03 but `clearFullLayers()` in TASK-07 is a bug. Same for types, file paths, env vars, table names.
+4. **Targets isolation** — does any task's Targets list overlap awkwardly with another in a way that will force out-of-order edits? If so, resequence or merge.
+5. **Verification reality** — every Done When has a corresponding Verification step that an engineer can actually run.
+
+## After the plan
+
+Save the plan, commit it, and tell the user:
+
+> Plan saved to `<path>` and committed. To execute, ask for tasks one at a time (e.g. "do TASK-01") — I'll stay inside that task's Targets and stop for approval before moving on, per the execution contract at the top of the plan. Or, if you want to hand this off to another LLM agent, run `/handoff-plan`.
+
+Do not start implementing in the same turn. Wait for the user to request the first task.

package/templates/instructions-block.md

@@ -0,0 +1,11 @@
+<!-- tuncss-plan-kit:start -->
+## Plan Kit
+
+This project uses tuncss-plan-kit. Three slash commands are available:
+
+- `/brainstorm` — turn an idea into an approved spec (writes to `docs/specs/`)
+- `/plan-universal` — turn a spec into an executable plan (writes to `docs/plans/`)
+- `/handoff-plan` — generate a paste-ready handoff for another LLM agent (writes to `docs/handoffs/`)
+
+Plans contain an execution contract at the top. When asked for a specific task ("do TASK-03"), read only that task's block, stay inside its Targets, stop and report when Done When + Verification are satisfied.
+<!-- tuncss-plan-kit:end -->