tuncss-plan-kit 0.4.0 → 0.6.0

package/README.md

@@ -54,7 +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/`).
 
-**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.
+**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. (Antigravity's docs list `~/.gemini/antigravity-cli/skills/` for the CLI, but in practice `agy` reads `~/.gemini/config/skills/` and ignores that folder, so the kit writes only the one.)
+
+`npx tuncss-plan-kit init --global` with no `--target` looks at your home directory instead of the current one and installs for every agent it finds: `~/.claude/` → Claude Code, `~/.codex/` → Codex CLI, `~/.gemini/config/` → Antigravity.
 
 Project-local is still the default for all three — recommended unless you specifically want the kit available everywhere.
 
@@ -70,7 +72,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
@@ -96,7 +98,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
 
@@ -106,7 +108,7 @@ npx tuncss-plan-kit init [--target=<list>] [--global] [--force]
 
 | Flag | Effect |
 |------|--------|
-| `--target=<list>` | Comma-separated. Values: `claude`, `codex`, `antigravity`, `all`. Auto-detected if omitted. |
+| `--target=<list>` | Comma-separated. Values: `claude`, `codex`, `antigravity`, `all`. Auto-detected if omitted (from the current directory, or from your home directory with `--global`). |
 | `--global` | Install to user-wide locations instead of the current project. |
 | `--force` | Overwrite existing skill/command files without warning. |
 

package/bin/cli.js

@@ -101,7 +101,8 @@ Commands:
 Options:
   --target  Comma-separated platforms to install for. Supported:
               claude, codex, antigravity, all
-            If omitted, auto-detects from the current directory.
+            If omitted, auto-detects from the current directory
+            (or from your home directory with --global).
   --global  Install to user-wide locations.
   --force   Overwrite existing skill/command files without warning.
             (Instruction-file marker blocks are always idempotent.)
@@ -139,6 +140,16 @@ function detectTargets(cwd) {
   return [...found];
 }
 
+// With --global the project directory says nothing about which agents the user
+// runs; their home directory does.
+function detectGlobalTargets(home) {
+  const found = [];
+  if (exists(path.join(home, ".claude"))) found.push("claude");
+  if (exists(path.join(home, ".codex"))) found.push("codex");
+  if (exists(path.join(home, ".gemini", "config"))) found.push("antigravity");
+  return found;
+}
+
 function ensureDir(dir) {
   fs.mkdirSync(dir, { recursive: true });
 }
@@ -284,10 +295,10 @@ function init(args) {
     targets = SUPPORTED.slice();
   }
   if (!targets) {
-    targets = detectTargets(cwd);
+    targets = args.global ? detectGlobalTargets(os.homedir()) : detectTargets(cwd);
     if (targets.length === 0) {
       console.error(
-        "No supported platform detected in this directory.\n" +
+        `No supported platform detected in ${args.global ? "your home directory" : "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"
       );

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,6 +1,6 @@
 {
   "name": "tuncss-plan-kit",
-  "version": "0.4.0",
+  "version": "0.6.0",
   "type": "module",
   "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": {

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 -->