tuncss-plan-kit 0.3.0 → 0.5.0

package/README.md

@@ -1,6 +1,6 @@
 # tuncss-plan-kit
 
-Four skills for spec-driven development, installable into Claude Code, Codex CLI, OpenCode, and Antigravity:
+Four skills for spec-driven development, installable into Claude Code, Codex CLI, and Antigravity:
 
 - **`/brainstorm`** — turn an idea into an approved spec (`docs/specs/`)
 - **`/plan-universal`** — turn a spec into an executable plan (`docs/plans/`)
@@ -23,9 +23,8 @@ The installer auto-detects which platform(s) the project uses and writes the rig
 |---|---|
 | `.claude/` or `CLAUDE.md` | Claude Code |
 | `.codex/` | Codex CLI |
-| `.opencode/` | OpenCode |
 | `.agents/` | Antigravity |
-| `AGENTS.md` (alone) | Codex, OpenCode, and Antigravity (they share `AGENTS.md`) |
+| `AGENTS.md` (alone) | Codex and Antigravity (they share `AGENTS.md`) |
 
 If nothing is detected, pass an explicit target:
 
@@ -45,10 +44,9 @@ Restart your coding agent after install so it picks up the new skills and slash
 |---|---|---|---|
 | 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` |
 | Antigravity | `.agents/skills/<n>/SKILL.md` | *(none — skills auto-expose as slash)* | `AGENTS.md` |
 
-Claude Code and Antigravity automatically expose any skill named `foo` as `/foo`, so the kit doesn't write wrapper command files for them. Codex and OpenCode don't auto-expose, so wrappers are written there to give you the same `/brainstorm`, `/plan-universal`, `/handoff-plan`, `/changelog` UX everywhere.
+Claude Code and Antigravity automatically expose any skill named `foo` as `/foo`, so the kit doesn't write wrapper command files for them. Codex doesn't auto-expose, so wrappers are written there to give you the same `/brainstorm`, `/plan-universal`, `/handoff-plan`, `/changelog` UX everywhere.
 
 Antigravity and Codex share `.agents/skills/`, so installing both writes those files once — the second platform reports them as already written.
 
@@ -56,11 +54,9 @@ Note: `agy changelog` is Antigravity's own built-in subcommand for release notes
 
 With `--global` the same files go to user-wide locations (`~/.claude/`, `~/.agents/`, `~/.codex/`, `~/.gemini/config/`).
 
-**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.)
-
 **Antigravity `--global` is a plain file copy to `~/.gemini/config/`** — a single location the desktop app, the `agy` CLI, and the IDE all read, so one install covers them all.
 
-Project-local is still the default for all four — recommended unless you specifically want the kit available everywhere.
+Project-local is still the default for all three — recommended unless you specifically want the kit available everywhere.
 
 ## Workflow
 
@@ -74,7 +70,7 @@ 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 /
+         tasks shaped as Targets / Implementation Notes /
          Done When / Verification
 
 You:     do TASK-01
@@ -100,7 +96,7 @@ Every plan starts with this contract:
 > 5. If verification fails, report the failure and stop. Do not attempt fixes outside the task's Targets, and do not write a changelog entry.
 > 6. **Changelog entry:** use the `changelog` skill to append this task's entry to `docs/CHANGELOG.md`. Base it on the actual diff, not on what you set out to do.
 
-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.
+Plans carry contracts (types, signatures, commands) and pointers to existing code, not pasted function bodies — the executor writes the code.
 
 ## Options
 
@@ -110,7 +106,7 @@ npx tuncss-plan-kit init [--target=<list>] [--global] [--force]
 
 | Flag | Effect |
 |------|--------|
-| `--target=<list>` | Comma-separated. Values: `claude`, `codex`, `opencode`, `antigravity`, `all`. Auto-detected if omitted. |
+| `--target=<list>` | Comma-separated. Values: `claude`, `codex`, `antigravity`, `all`. Auto-detected if omitted. |
 | `--global` | Install to user-wide locations instead of the current project. |
 | `--force` | Overwrite existing skill/command files without warning. |
 
@@ -118,6 +114,11 @@ npx tuncss-plan-kit init [--target=<list>] [--global] [--force]
 
 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 four files that cover the only loop most projects need: design → plan → execute (here or elsewhere) → record. That's it.
 
+## A note on OpenCode
+
+OpenCode was supported through v0.3.0. It was dropped in v0.4.0 because nobody
+on the team uses it any more. If you need it, pin `tuncss-plan-kit@0.3.0`.
+
 ## License
 
 MIT

package/bin/cli.js

@@ -3,12 +3,10 @@
 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", "changelog"];
 const COMMANDS = ["brainstorm", "plan-universal", "handoff-plan", "changelog"];
@@ -45,18 +43,6 @@ const PLATFORMS = {
     }),
     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",
-  },
   // Antigravity reads .agents/ in a workspace and ~/.gemini/config/ globally.
   // One global location serves all three variants (desktop app, agy CLI, IDE).
   // Like Claude Code, it expands skills into slash commands on its own, so no
@@ -109,17 +95,14 @@ 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).
+  init      Install the four skills (brainstorm, plan-universal, handoff-plan,
+            changelog) into the target platform(s).
 
 Options:
   --target  Comma-separated platforms to install for. Supported:
-              claude, codex, opencode, antigravity, all
+              claude, codex, antigravity, 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.)
 
@@ -146,16 +129,12 @@ function detectTargets(cwd) {
     found.add("claude");
   }
   if (exists(path.join(cwd, ".codex"))) found.add("codex");
-  if (exists(path.join(cwd, ".opencode"))) found.add("opencode");
   // Antigravity discovers .agents/ and reads AGENTS.md as rules. Its project
   // paths are a subset of Codex's, so adding it here costs no extra files.
   if (exists(path.join(cwd, ".agents"))) found.add("antigravity");
   if (exists(path.join(cwd, "AGENTS.md"))) {
     found.add("antigravity");
-    if (!found.has("codex") && !found.has("opencode")) {
-      found.add("codex");
-      found.add("opencode");
-    }
+    if (!found.has("codex")) found.add("codex");
   }
   return [...found];
 }
@@ -297,105 +276,6 @@ function installPlatform({ platform, isGlobal, force, baseRoot, sharedState }) {
   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
-  // Pass the full command as a single string with shell: true to avoid the
-  // Node DEP0190 warning about unescaped args concatenation. Args are all
-  // hardcoded here so there's no injection surface.
-  const npmBin = process.platform === "win32" ? "npm.cmd" : "npm";
-  const npmRes = spawnSync(`${npmBin} install --silent --no-audit --no-fund`, {
-    cwd: ocDir,
-    stdio: "inherit",
-    shell: true,
-  });
-  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();
 
@@ -439,19 +319,14 @@ function init(args) {
 
   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);
-    }
+    const lines = installPlatform({
+      platform,
+      isGlobal: args.global,
+      force: args.force,
+      baseRoot: cwd,
+      sharedState,
+    });
+    for (const l of lines) console.log(l);
     console.log("");
   }
 

package/commands/codex/brainstorm.md

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

package/commands/codex/changelog.md

@@ -1 +1 @@
-Use the `changelog` skill to handle the user's request.
+Use the `changelog` skill to handle the user's request.

package/commands/codex/handoff-plan.md

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

package/commands/codex/plan-universal.md

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

package/package.json

@@ -1,8 +1,7 @@
 {
   "name": "tuncss-plan-kit",
-  "version": "0.3.0",
+  "version": "0.5.0",
   "type": "module",
-  "main": ".opencode/plugins/tuncss-plan-kit.js",
   "description": "Four-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, and record what changed.",
   "bin": {
     "tuncss-plan-kit": "bin/cli.js"
@@ -12,7 +11,6 @@
     "skills/",
     "commands/",
     "templates/",
-    ".opencode/",
     "README.md"
   ],
   "keywords": [

package/skills/brainstorm/SKILL.md

@@ -1,132 +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
+---
+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 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/changelog/SKILL.md

@@ -1,95 +1,95 @@
----
-name: changelog
-description: Use when a plan task has just been completed, or when the user runs /changelog, to append a short entry describing what actually changed to docs/CHANGELOG.md.
----
-
-# Changelog
-
-Append a short, concrete record of what changed to `docs/CHANGELOG.md`. The reader is a teammate who did not do the work and wants to know what is different now. Commit messages already failed at this — do not write another one.
-
-**Announce at start:** "Writing the changelog entry."
-
-## Two ways in
-
-**From a completed plan task.** Rule 6 of the plan's execution contract sends you here once Done When and Verification are satisfied. You have the task id, the task name, and the plan path.
-
-**From `/changelog`.** The user invoked it directly for work done outside the plan flow. There is no task id and no plan path.
-
-If a task's verification failed, do not write an entry at all. That work is usually not merged, and recording it would put a change that did not happen into the log.
-
-## Gather the facts first
-
-Run these before writing anything. Never write an entry from memory of what you set out to do — write it from what actually landed.
-
-- `git diff` and `git diff --staged` — the real change
-- `git config user.name` — the author name
-
-The diff is your source, not your content: it tells you what to write about, and none of it is copied into the entry.
-
-If both diffs are empty and nothing was just committed for this work, stop and tell the user there is nothing to record.
-
-## How to write the bullets
-
-This is the whole skill. Everything else is placement.
-
-1. Every bullet names the thing that changed.
-2. If a value changed, give **old → new**.
-3. Banned: any phrasing that does not say what became what. "Improved", "refactored", "fixed issues", "optimized", "cleaned up", "enhanced" — and their equivalents in any language.
-4. One to five bullets per entry. If you need more than five, say so in your report to the user: the task was too large. Write the entry anyway.
-5. Write in the language the repository uses. This skill is in English; the entries it produces are not necessarily.
-
-Good:
-- `Read threshold lowered from -60 dB to -80 dB`
-- `Token validation moved out of every handler into a single requireAuth middleware`
-- `Session lifetime cut from 24 hours to 2 hours`
-
-Bad:
-- `Improved bluetooth reliability` — what became what?
-- `Refactored auth` — same.
-- `Various fixes` — same.
-
-## Entry shape
-
-For a plan task:
-
-```markdown
-### <task name> — TASK-NN · <author> · [plan](<plan path>)
-- <bullet>
-- <bullet>
-```
-
-For off-plan work:
-
-```markdown
-### <short name> — off-plan · <author>
-- <bullet>
-```
-
-The `off-plan` label is written in the repository's language, like the bullets.
-
-If `git config user.name` is empty, drop both the author and the `·` that separates it. Never invent a name.
-
-## Where it goes
-
-The file is `docs/CHANGELOG.md`. Create it if missing, with `# Changelog` as the first line.
-
-Entries are grouped under date headings, newest first:
-
-```markdown
-# Changelog
-
-## 2026-09-04
-
-### Auth middleware — TASK-03 · Mustafa TUNÇ · [plan](docs/plans/2026-09-02-auth.md)
-- Token validation moved out of every handler into a single requireAuth middleware
-- Response on an invalid token changed from 200 with an empty body to 401
-```
-
-Placement rule — follow it exactly, so that three people's agents do not grow the file from three different places:
-
-- If today's date heading already exists, append the entry at the end of that section.
-- If it does not, insert a new date heading immediately after the `# Changelog` line.
-
-## Do not commit
-
-Leave the entry in the working tree next to the change. Whoever commits the work commits the entry with it, so `git log -p docs/CHANGELOG.md` always pairs a line with the change that produced it.
+---
+name: changelog
+description: Use when a plan task has just been completed, or when the user runs /changelog, to append a short entry describing what actually changed to docs/CHANGELOG.md.
+---
+
+# Changelog
+
+Append a short, concrete record of what changed to `docs/CHANGELOG.md`. The reader is a teammate who did not do the work and wants to know what is different now. Commit messages already failed at this — do not write another one.
+
+**Announce at start:** "Writing the changelog entry."
+
+## Two ways in
+
+**From a completed plan task.** Rule 6 of the plan's execution contract sends you here once Done When and Verification are satisfied. You have the task id, the task name, and the plan path.
+
+**From `/changelog`.** The user invoked it directly for work done outside the plan flow. There is no task id and no plan path.
+
+If a task's verification failed, do not write an entry at all. That work is usually not merged, and recording it would put a change that did not happen into the log.
+
+## Gather the facts first
+
+Run these before writing anything. Never write an entry from memory of what you set out to do — write it from what actually landed.
+
+- `git diff` and `git diff --staged` — the real change
+- `git config user.name` — the author name
+
+The diff is your source, not your content: it tells you what to write about, and none of it is copied into the entry.
+
+If both diffs are empty and nothing was just committed for this work, stop and tell the user there is nothing to record.
+
+## How to write the bullets
+
+This is the whole skill. Everything else is placement.
+
+1. Every bullet names the thing that changed.
+2. If a value changed, give **old → new**.
+3. Banned: any phrasing that does not say what became what. "Improved", "refactored", "fixed issues", "optimized", "cleaned up", "enhanced" — and their equivalents in any language.
+4. One to five bullets per entry. If you need more than five, say so in your report to the user: the task was too large. Write the entry anyway.
+5. Write in the language the repository uses. This skill is in English; the entries it produces are not necessarily.
+
+Good:
+- `Read threshold lowered from -60 dB to -80 dB`
+- `Token validation moved out of every handler into a single requireAuth middleware`
+- `Session lifetime cut from 24 hours to 2 hours`
+
+Bad:
+- `Improved bluetooth reliability` — what became what?
+- `Refactored auth` — same.
+- `Various fixes` — same.
+
+## Entry shape
+
+For a plan task:
+
+```markdown
+### <task name> — TASK-NN · <author> · [plan](<plan path>)
+- <bullet>
+- <bullet>
+```
+
+For off-plan work:
+
+```markdown
+### <short name> — off-plan · <author>
+- <bullet>
+```
+
+The `off-plan` label is written in the repository's language, like the bullets.
+
+If `git config user.name` is empty, drop both the author and the `·` that separates it. Never invent a name.
+
+## Where it goes
+
+The file is `docs/CHANGELOG.md`. Create it if missing, with `# Changelog` as the first line.
+
+Entries are grouped under date headings, newest first:
+
+```markdown
+# Changelog
+
+## 2026-09-04
+
+### Auth middleware — TASK-03 · Mustafa TUNÇ · [plan](docs/plans/2026-09-02-auth.md)
+- Token validation moved out of every handler into a single requireAuth middleware
+- Response on an invalid token changed from 200 with an empty body to 401
+```
+
+Placement rule — follow it exactly, so that three people's agents do not grow the file from three different places:
+
+- If today's date heading already exists, append the entry at the end of that section.
+- If it does not, insert a new date heading immediately after the `# Changelog` line.
+
+## Do not commit
+
+Leave the entry in the working tree next to the change. Whoever commits the work commits the entry with it, so `git log -p docs/CHANGELOG.md` always pairs a line with the change that produced it.

package/skills/plan-universal/SKILL.md

@@ -55,17 +55,6 @@ Every plan starts with this header:
 ---
 ````
 
-## 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:
@@ -77,13 +66,12 @@ Every task uses this shape:
 - `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
+- The contract the executor can't guess: types, function signatures, commands, config keys. Write code bodies only for logic that is genuinely non-obvious (an algorithm, a regex, a query, a tricky edge case) — the executor writes the rest
+- Point to existing code instead of copying it: "follow the handler pattern in `src/routes/users.ts:40`"
+- If a public interface from an earlier task is consumed here, restate its signature only; don't make the reader page back
 
 **Done When:**
 - Bullet list of observable outcomes
@@ -117,7 +105,7 @@ These are **plan failures**. Never write them:
 - "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
+- Steps that describe *what* without pointing to *how* — name the existing file to follow, the signature, or the exact command; don't paste whole function bodies the executor can write itself
 - References to types, functions, or files not defined in any task or in the file map
 
 ## Self-review

package/templates/instructions-block.md

@@ -1,12 +1,12 @@
-<!-- tuncss-plan-kit:start -->
-## Plan Kit
-
-This project uses tuncss-plan-kit. Four 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/`)
-- `/changelog` — record what changed, in plain sentences (writes to `docs/CHANGELOG.md`)
-
-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, write the changelog entry, then stop and report when Done When + Verification are satisfied.
-<!-- tuncss-plan-kit:end -->
+<!-- tuncss-plan-kit:start -->
+## Plan Kit
+
+This project uses tuncss-plan-kit. Four 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/`)
+- `/changelog` — record what changed, in plain sentences (writes to `docs/CHANGELOG.md`)
+
+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, write the changelog entry, then stop and report when Done When + Verification are satisfied.
+<!-- tuncss-plan-kit:end -->

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

@@ -1,48 +0,0 @@
-import path from "path";
-import { fileURLToPath } from "url";
-
-const __dirname = path.dirname(fileURLToPath(import.meta.url));
-const skillsDir = path.resolve(__dirname, "../../skills");
-
-// Minimal templates: just pass the user's input through. The skill's
-// `description` frontmatter is what triggers the model to invoke the skill
-// when relevant — we don't force-load it from the wrapper, which would
-// dump the full SKILL.md body into the chat in OpenCode's UI.
-const WRAPPERS = {
-  brainstorm: {
-    description: "Turn an idea into an approved spec",
-    template: "$ARGUMENTS\n",
-  },
-  "plan-universal": {
-    description: "Turn an approved spec into an executable implementation plan",
-    template: "$ARGUMENTS\n",
-  },
-  "handoff-plan": {
-    description:
-      "Generate a paste-ready handoff message for another LLM agent to execute the plan",
-    template: "$ARGUMENTS\n",
-  },
-  changelog: {
-    description: "Record what changed in docs/CHANGELOG.md",
-    template: "$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/commands/opencode/brainstorm.md

@@ -1,5 +0,0 @@
----
-description: Turn an idea into an approved spec
----
-
-$ARGUMENTS

package/commands/opencode/changelog.md

@@ -1,5 +0,0 @@
----
-description: Record what changed in docs/CHANGELOG.md
----
-
-$ARGUMENTS

package/commands/opencode/handoff-plan.md

@@ -1,5 +0,0 @@
----
-description: Generate a paste-ready handoff message for another LLM agent to execute the plan
----
-
-$ARGUMENTS

package/commands/opencode/plan-universal.md

@@ -1,5 +0,0 @@
----
-description: Turn an approved spec into an executable implementation plan
----
-
-$ARGUMENTS