tuncss-plan-kit 0.5.0 → 0.7.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.
 
@@ -73,28 +75,51 @@ Agent:   ↓ writing-plans skill
          tasks shaped as Targets / Implementation Notes /
          Done When / Verification
 
-You:     do TASK-01
-Agent:   reads only TASK-01's block, stays inside its Targets, writes the
-         changelog entry to docs/CHANGELOG.md, stops for approval when done
+You:     run the plan
+Agent:   runs every task in order; after each one it writes the changelog
+         entry to docs/CHANGELOG.md and commits; stops only on a stop
+         condition (S1–S4) and reports where and why
 
 — 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)
+         writes a briefing to docs/handoffs/ — the execution contract on
+         top — that you can paste into another agent
 ```
 
 ## 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, write the changelog entry (rule 6), then **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, 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.
+> **Default: run every task in order, from TASK-01 to the last, without stopping between tasks.**
+> If the user names a single task ("do TASK-03"), do only that task, then stop.
+> If the user names a starting task ("run from TASK-04"), start there and continue in order.
+> This plan is already approved. Do not write your own plan or task list — execute this one.
+>
+> **Before the first task:** run `git status`. If the working tree is not clean, stop (S4).
+>
+> **For each task:**
+> 1. Read only that task's block. Do not preview later tasks.
+> 2. Edit only the files in its **Targets**.
+> 3. Follow its **Implementation Notes**; add no extra scope.
+> 4. Run its **Verification**. If it fails, make one fix attempt inside Targets and run it again.
+> 5. When **Done When** and **Verification** pass: append the changelog entry with the `changelog`
+>    skill (from the actual diff), then commit the task's changes and the entry together.
+> 6. **Commit message:** Turkish, ASCII only — write c, s, i, g, o, u instead of ç, ş, ı, ğ, ö, ü.
+>    First line `TASK-NN: <what changed>`, under 72 characters. Say what changed, not "dosyalar guncellendi".
+>    Example: `TASK-03: Oturum suresi 24 saatten 2 saate dusuruldu`
+>
+> **Stop and report when:**
+> - S1: Verification fails a second time.
+> - S2: A file, function, API, flag, or command the task names does not exist or differs from the description. Do not guess.
+> - S3: Finishing the task requires editing a file outside its Targets.
+> - S4: The working tree was not clean before the first task.
+>
+> On stop: no changelog entry and no commit for that task; earlier commits stay. Report the task id, the condition (S1–S4), and what you saw.
+> After the last task: report the list of commits made.
+
+Commit messages are Turkish, ASCII only — the kit's team writes them that way.
 
 Plans carry contracts (types, signatures, commands) and pointers to existing code, not pasted function bodies — the executor writes the code.
 
@@ -106,7 +131,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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tuncss-plan-kit",
-  "version": "0.5.0",
+  "version": "0.7.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/changelog/SKILL.md

@@ -11,7 +11,7 @@ Append a short, concrete record of what changed to `docs/CHANGELOG.md`. The read
 
 ## 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 a completed plan task.** Step 5 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.
 
@@ -92,4 +92,4 @@ Placement rule — follow it exactly, so that three people's agents do not grow
 
 ## 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.
+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. In a plan run, the execution contract commits the task's changes and this entry together right after you finish.

package/skills/handoff-plan/SKILL.md

@@ -43,7 +43,35 @@ 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.
+You're executing an approved implementation plan in this repo.
+
+<!-- EXECUTION CONTRACT — read before touching any task -->
+> **Default: run every task in order, from TASK-01 to the last, without stopping between tasks.**
+> If the user names a single task ("do TASK-03"), do only that task, then stop.
+> If the user names a starting task ("run from TASK-04"), start there and continue in order.
+> This plan is already approved. Do not write your own plan or task list — execute this one.
+>
+> **Before the first task:** run `git status`. If the working tree is not clean, stop (S4).
+>
+> **For each task:**
+> 1. Read only that task's block. Do not preview later tasks.
+> 2. Edit only the files in its **Targets**.
+> 3. Follow its **Implementation Notes**; add no extra scope.
+> 4. Run its **Verification**. If it fails, make one fix attempt inside Targets and run it again.
+> 5. When **Done When** and **Verification** pass: append the changelog entry with the `changelog`
+>    skill (from the actual diff), then commit the task's changes and the entry together.
+> 6. **Commit message:** Turkish, ASCII only — write c, s, i, g, o, u instead of ç, ş, ı, ğ, ö, ü.
+>    First line `TASK-NN: <what changed>`, under 72 characters. Say what changed, not "dosyalar guncellendi".
+>    Example: `TASK-03: Oturum suresi 24 saatten 2 saate dusuruldu`
+>
+> **Stop and report when:**
+> - S1: Verification fails a second time.
+> - S2: A file, function, API, flag, or command the task names does not exist or differs from the description. Do not guess.
+> - S3: Finishing the task requires editing a file outside its Targets.
+> - S4: The working tree was not clean before the first task.
+>
+> On stop: no changelog entry and no commit for that task; earlier commits stay. Report the task id, the condition (S1–S4), and what you saw.
+> After the last task: report the list of commits made.
 
 **Project:** <project name> — <one-line description>
 
@@ -59,20 +87,12 @@ You're picking up an implementation plan in this repo.
 - 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, write the changelog entry (rule 6), then **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, and don't 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.
-
-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.
+Start now: open `<plan path>`, read the header and TASK-01's block, and begin. Continue through every task in order until the last one is done or a stop condition (S1–S4) is hit.
 ````
 
 ## Rules
 
 - Don't summarize task bodies. The receiving agent reads the plan file itself.
-- Don't reformat the execution contract beyond the 6 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 reformat the execution contract. It is copied verbatim from the plan-universal header; the plan file is the source of truth.
+- Keep the message under ~60 lines, not counting the task list. 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

@@ -33,13 +33,32 @@ Every plan starts with this header:
 # <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, write the changelog entry (rule 6), then **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, 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.
+> **Default: run every task in order, from TASK-01 to the last, without stopping between tasks.**
+> If the user names a single task ("do TASK-03"), do only that task, then stop.
+> If the user names a starting task ("run from TASK-04"), start there and continue in order.
+> This plan is already approved. Do not write your own plan or task list — execute this one.
+>
+> **Before the first task:** run `git status`. If the working tree is not clean, stop (S4).
+>
+> **For each task:**
+> 1. Read only that task's block. Do not preview later tasks.
+> 2. Edit only the files in its **Targets**.
+> 3. Follow its **Implementation Notes**; add no extra scope.
+> 4. Run its **Verification**. If it fails, make one fix attempt inside Targets and run it again.
+> 5. When **Done When** and **Verification** pass: append the changelog entry with the `changelog`
+>    skill (from the actual diff), then commit the task's changes and the entry together.
+> 6. **Commit message:** Turkish, ASCII only — write c, s, i, g, o, u instead of ç, ş, ı, ğ, ö, ü.
+>    First line `TASK-NN: <what changed>`, under 72 characters. Say what changed, not "dosyalar guncellendi".
+>    Example: `TASK-03: Oturum suresi 24 saatten 2 saate dusuruldu`
+>
+> **Stop and report when:**
+> - S1: Verification fails a second time.
+> - S2: A file, function, API, flag, or command the task names does not exist or differs from the description. Do not guess.
+> - S3: Finishing the task requires editing a file outside its Targets.
+> - S4: The working tree was not clean before the first task.
+>
+> On stop: no changelog entry and no commit for that task; earlier commits stay. Report the task id, the condition (S1–S4), and what you saw.
+> After the last task: report the list of commits made.
 
 **Goal:** <one sentence>
 
@@ -83,7 +102,7 @@ Every task uses this shape:
 - 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.
+Tasks are self-contained because the executor reads exactly one block at a time (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
 
@@ -107,6 +126,7 @@ These are **plan failures**. Never write them:
 - "Similar to TASK-N" — repeat what's needed; the executor reads tasks out of order
 - 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
+- References you haven't verified — every file, function, command, flag, and config key in Implementation Notes either exists in the repo (open it and check while writing the plan) or is created by an earlier task's Targets. If you can't confirm it, don't write it.
 
 ## Self-review
 
@@ -116,12 +136,14 @@ After the plan is written, re-read it against the spec with fresh eyes. Fix issu
 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.
+5. **Verification reality** — every Done When has a corresponding Verification step that an engineer can actually run. Every Verification command terminates on its own — no watch mode, no dev server left running; the executor runs tasks back to back and a hung command blocks the whole run.
+6. **Order** — each task may assume only that earlier tasks are done. The executor runs them top to bottom.
+7. **References exist** — every path, function, and command named in a task exists in the repo or is created by an earlier task.
 
 ## 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`.
+> Plan saved to `<path>` and committed. To execute every task in order, say "run the plan" — I'll commit after each task and stop only on a stop condition (S1–S4). To run a single task, say "do TASK-01". To hand it to another LLM agent, run `/handoff-plan`.
 
-Do not start implementing in the same turn. Wait for the user to request the first task.
+Do not start implementing in the same turn. Wait for the user to say how to run it.

package/templates/instructions-block.md

@@ -8,5 +8,5 @@ This project uses tuncss-plan-kit. Four slash commands are available:
 - `/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.
+Plans contain an execution contract at the top. By default, run every task in order: after each task passes its Verification, write the changelog entry and commit; stop only on a stop condition (S1–S4). "do TASK-03" runs only that task.
 <!-- tuncss-plan-kit:end -->