@simplysm/sd-claude 13.0.84 → 13.0.85

package/claude/rules/sd-claude-rules.md

@@ -9,6 +9,8 @@
 ## Playwright Rules
 
 - All Playwright output (screenshots, PDFs, downloads, etc.) must be saved to the `.tmp/playwright/` directory.
+- When using Playwright MCP tools with a `filename` parameter, always prefix the filename with `.tmp/playwright/` (e.g., `filename: ".tmp/playwright/my-screenshot.png"`).
+- Never pass a bare filename without the `.tmp/playwright/` path prefix.
 
 ## Documentation Rules for LLMs
 

package/claude/rules/sd-library-issue.md

@@ -0,0 +1,7 @@
+# Simplysm Library Issue Reporting
+
+Source code for `@simplysm/*` packages can be found in `node_modules/@simplysm/`. If debugging reveals the root cause is in the simplysm library itself, generate a GitHub issue-formatted text (title, reproduction steps, expected behavior, actual behavior) and display it to the user.
+
+**Report facts only — do not suggest fixes or include code location hints. Do not auto-submit the issue — only display the text.**
+
+The issue body must NEVER include internal analysis of library code (class names, variable names, style properties, inheritance chains, etc.). Only describe user-observable symptoms.

package/claude/sd-statusline.py

@@ -218,8 +218,11 @@ def main():
     model = format_model(model_id) if model_id else "?"
 
     # Extract context %
-    ctx_pct = stdin_data.get("context_window", {}).get("used_percentage")
-    ctx_str = f"{ctx_pct}%" if ctx_pct is not None else "?"
+    ctx_window = stdin_data.get("context_window")
+    if ctx_window is not None:
+        ctx_str = f"{ctx_window.get('used_percentage') or 0}%"
+    else:
+        ctx_str = "?"
 
     # Read cached usage data
     cache = read_cache()

package/claude/skills/sd-api-review/SKILL.md

@@ -83,7 +83,3 @@ Improvement:
 ## Step 5: Execute the Plan
 
 Once sd-plan is complete and a finalized plan is produced, modify the code according to that plan.
-
-## Step 6: Recommend README Update
-
-If code modifications were made, recommend the user to run `/sd-readme`.

package/claude/skills/sd-check/SKILL.md

@@ -54,7 +54,11 @@ Invoke `sd-debug` via the Skill tool. Pass the following content as args:
 
 ```
 Analyze the code errors from the check results below.
-**Important: After completing Step 2 (in-depth codebase analysis), skip Steps 3-5 and immediately fix the code based on the analysis results. Do not output a diagnostic report, do not wait for user confirmation, and do not invoke sd-plan — apply fixes directly.**
+**Important workflow instructions:**
+1. Perform Steps 1-2 thoroughly — gather problem information and conduct in-depth codebase analysis to identify the root cause. Do NOT skip or rush these steps.
+2. Output the diagnostic report from Step 3, but skip the user confirmation (do not call AskUserQuestion).
+3. Skip Steps 4-5 (do not invoke sd-plan).
+4. Based on the analysis results and diagnostic report, apply fixes directly.
 
 <Include the error content from the check result file here>
 ```

package/claude/skills/sd-plan/SKILL.md

@@ -7,6 +7,33 @@ description: This skill is used when the user requests "make a plan", "create a
 
 Receives a task request from the user, generates an initial plan, then iteratively reviews and asks questions about unclear parts to produce a perfectly clear plan.
 
+## MANDATORY RULE — ONE QUESTION PER AskUserQuestion CALL
+
+**Every AskUserQuestion call MUST have exactly 1 item in the `questions` array. NEVER bundle 2+ questions.**
+
+WRONG — bundling multiple questions:
+```
+questions: [
+  { question: "Which API style?" ... },
+  { question: "Which styling approach?" ... },
+  { question: "What default value?" ... }
+]
+```
+
+RIGHT — one question per call, sequential:
+```
+// Call 1
+questions: [{ question: "Which API style?" ... }]
+// Wait for answer → apply → re-extract unclear items
+// Call 2
+questions: [{ question: "Which styling approach?" ... }]
+// Wait for answer → apply → re-extract unclear items
+// Call 3
+questions: [{ question: "What default value?" ... }]
+```
+
+**Violating this rule makes the output unusable. There is NO exception.**
+
 ---
 
 ## Step 1: Input Verification
@@ -23,26 +50,47 @@ Receives a task request from the user, generates an initial plan, then iterative
 
 ### 2-1. Draft Creation
 
-Draft the plan. Always follow TDD principles:
-- For code tasks → Write test code first
-- For non-code tasks → Define a self-verification checklist first
-- For code tasks where the project has no test environment set up → Propose verification methods such as CLI or dry-run
+Draft the plan. **Every implementation item MUST be structured as 3 sub-steps: RED → Implement → GREEN.** NEVER skip or merge these sub-steps regardless of task simplicity.
+
+Classify the task first, then apply the matching TDD approach:
+
+**If code + test env exists:**
+1. **RED** — Write a failing test file, run it → confirm FAIL
+2. **Implement** — Write the minimum code to pass
+3. **GREEN** — Run the test → confirm PASS
+
+**If code + no test env:**
+1. **RED** — Define a CLI/dry-run command, run it → confirm FAIL
+2. **Implement** — Write the minimum code to pass
+3. **GREEN** — Run the same command → confirm PASS
+
+**If non-code (config, docs, prompts, SKILL.md, etc.):**
+Prompt/config files cannot be unit-tested. Use **Agent behavioral simulation**: launch an Agent that reads the file and naturally follows its instructions with a sample task. **Do NOT tell the Agent what behavior you are testing** (this biases the result and invalidates the test).
+1. **RED** — `git stash` your changes → launch Agent with a sample task against the **original** file → confirm the Agent's output shows the **problematic** behavior (FAIL)
+2. **Implement** — `git stash pop` to restore changes, then apply your edits
+3. **GREEN** — launch same Agent with the same task against the **modified** file → confirm the Agent's output shows the **desired** behavior (PASS). If FAIL → fix implementation → re-run GREEN until PASS.
 
 ### 2-2. Clarification Cycle
 
-Repeat the following **until there are 0 unclear items**:
+**This is a single-item loop. Each iteration handles exactly ONE unclear item, then restarts from scratch.**
 
-1. **Extract**: Compare the plan against all 12 "Ambiguity Criteria" listed below and enumerate all unclear items.
-2. **Dependency analysis**: Identify dependencies between items. ("A must be decided before B can be asked" → B depends on A)
-3. **Ask**: For items with no dependencies, use AskUserQuestion with **exactly one question per tool call**. Provide 2-5 options for each question.
-   - For each item, repeat "present one explanation -> AskUserQuestion"
-4. **Apply**: Incorporate all answers to update the plan, then return to step 1.
+1. **Extract**: Compare the plan against all 12 "Ambiguity Criteria" below → enumerate unclear items.
+   - 0 unclear items → **STOP this loop. Go to Step 2.5.**
+2. **Dependency analysis**: Identify dependencies. ("A must be decided before B" → B depends on A)
+3. **Ask exactly ONE question**: Pick the single most important item with no unresolved dependencies.
+   a. Present a brief explanation of why this item is unclear.
+   b. Call AskUserQuestion with `questions` array containing **exactly 1 item**. Include 2-5 options.
+   c. **STOP and WAIT** for the user's answer. Do NOT plan, prepare, or output anything about the next question.
+4. **Apply**: Incorporate the answer into the plan.
+5. **RESTART from step 1** — re-extract ALL unclear items from scratch. The previous answer may have resolved multiple items or created new ones. Never assume the remaining questions are still valid.
 
-0 unclear items → Move to **Step 2.5 Final Verification**.
+**NEVER ask 2+ questions before restarting the loop. NEVER plan ahead for "the next question". Each loop iteration = 1 Extract + 1 Question + 1 Answer.**
 
 ### Ambiguity Criteria
 
 > **Core principle**: Anything not explicitly stated by the user and not confirmed in the codebase is **treated as speculation/assumption** and classified as an unclear item. Even if Claude wrote it confidently, it is unclear if the source is unverified.
+>
+> **Exception — implementation details are NOT unclear items**: Technical decisions about HOW to achieve the goal (code placement, internal structure, naming conventions, file organization, etc.) are Claude's engineering judgment. Only user-facing requirements (WHAT behavior the user wants) should be classified as unclear. If the user did not specify it and it is purely a technical approach decision, Claude decides — do NOT ask the user.
 
 Compare against all 12 items below **during every review**. To skip an item as "not applicable", there must be concrete evidence (user statement or codebase confirmation).
 
@@ -88,17 +136,30 @@ If the user approves, Write the plan to `.tmp/plans/${TS}_{topic}.md`.
 
 ## Step 4: Post-Implementation Guidance
 
-If the user approves implementation, implement according to the plan. Once implementation is complete, output the following guidance:
+If the user approves implementation, implement according to the plan. Follow the TDD approach defined in Step 2-1 for the task type. **Do NOT proceed to the next item until the current item reaches GREEN.**
+
+### TDD Execution Rules
+
+**RED and GREEN must be actually executed. NEVER skip or substitute them.**
+
+- "User already confirmed the issue" is NOT a valid RED. Run the test yourself.
+- "Needs a separate session to verify" is NOT a valid GREEN. Run the test yourself.
+- If GREEN fails → fix the implementation → re-run GREEN. Repeat until it passes.
+
+Once all items are complete, output the following guidance. Include only the items whose conditions are met, numbered sequentially:
 
-- **If code changes are included**:
-  ```
-  Implementation is complete. It is recommended to run the following steps in order:
-  1. /sd-check — Type check + lint + test inspection and auto-fix
-  2. /sd-simplify — Simplification review of changed code
-  3. /sd-commit — Commit changes
-  ```
+| Condition | Recommendation |
+|-----------|----------------|
+| Code changes exist | `/sd-check` — Type check + lint + test inspection and auto-fix |
+| Code changes exist | `/sd-simplify` — Simplification review of changed code |
+| Public API changed (exports, public methods/properties, component props, etc.) | `/sd-readme` — Update README documentation |
+| Always | `/sd-commit` — Commit changes |
 
-- **If no code changes are involved** (configuration, documentation, etc.):
-  ```
-  Implementation is complete. Run /sd-commit to commit the changes.
-  ```
+Example (all conditions met):
+```
+Implementation is complete. It is recommended to run the following steps in order:
+1. /sd-check — Type check + lint + test inspection and auto-fix
+2. /sd-simplify — Simplification review of changed code
+3. /sd-readme — Update README documentation
+4. /sd-commit — Commit changes
+```

package/claude/skills/sd-review/SKILL.md

@@ -30,7 +30,12 @@ Do not modify the code under any circumstances. Only compile and output a list o
 
 Write each finding in the following format:
 ```
-- **filepath:line** — Problem description — Suggested fix
+- **filepath:line**
+  - Current code: (excerpt of the relevant code)
+  - Problem description:
+  - Suggested fix:
+  - Reasons to fix: Rationale for applying the fix
+  - Reasons not to fix: Rationale for keeping the current code
 ```
 
 If no findings are discovered, display "No potential bugs were found." and stop.
@@ -52,9 +57,11 @@ When asking the user about uncertain fixes, **always present** the following inf
 ```
 Fix:
 - Filepath:line:
-- Problem description:
 - Current code: (excerpt of the relevant code)
+- Problem description:
 - Suggested fix:
+- Reasons to fix:
+- Reasons not to fix:
 ```
 
 <Full list of findings from Step 2>

package/claude/skills/sd-simplify/SKILL.md

@@ -24,7 +24,12 @@ Invoke `simplify` using the Skill tool. Pass the following instructions as args:
 Review the current codebase at the <target path> path. (Not recently changed code)
 Do NOT modify any code. Only compile and output a list of items to fix.
 Write each item in the following format:
-- **file-path:line** — Problem description — Suggested improvement
+- **file-path:line**
+  - Current code: (excerpt of the relevant code)
+  - Problem description:
+  - Suggested improvement:
+  - Reasons to change: Rationale for applying the improvement
+  - Reasons not to change: Rationale for keeping the current code
 ```
 
 Replace the `<target path>` placeholder with the actual path extracted in Step 1.
@@ -46,9 +51,11 @@ When asking the user about unclear suggestions, **always present** the following
 ```
 Suggestion:
 - File path:line:
-- Problem description:
 - Current code: (excerpt of the relevant code)
+- Problem description:
 - Suggested improvement:
+- Reasons to change:
+- Reasons not to change:
 ```
 
 <Full list of items to fix from Step 2>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@simplysm/sd-claude",
-  "version": "13.0.84",
+  "version": "13.0.85",
   "description": "Simplysm Claude Code asset installer",
   "author": "simplysm",
   "license": "Apache-2.0",
@@ -10,6 +10,9 @@
     "directory": "packages/sd-claude"
   },
   "type": "module",
+  "bin": {
+    "sd-claude": "scripts/cli.mjs"
+  },
   "files": [
     "scripts",
     "claude"

package/scripts/cli.mjs

@@ -0,0 +1,12 @@
+#!/usr/bin/env node
+
+const command = process.argv[2];
+
+if (command === "postinstall") {
+  await import("./postinstall.mjs");
+} else {
+  console.log("Usage: sd-claude <command>");
+  console.log("Commands:");
+  console.log("  postinstall   Install Claude Code assets to .claude/");
+  process.exit(1);
+}

package/scripts/postinstall.mjs

@@ -46,7 +46,7 @@ try {
   console.warn("[@simplysm/sd-claude] postinstall warning:", err.message);
 }
 
-/** Finds the project root from INIT_CWD or node_modules path. */
+/** Finds the project root from INIT_CWD, node_modules path, or cwd. */
 function findProjectRoot(dirname) {
   if (process.env["INIT_CWD"] != null) {
     return process.env["INIT_CWD"];
@@ -55,7 +55,12 @@ function findProjectRoot(dirname) {
   const sep = path.sep;
   const marker = sep + "node_modules" + sep;
   const idx = dirname.indexOf(marker);
-  return idx !== -1 ? dirname.substring(0, idx) : undefined;
+  if (idx !== -1) {
+    return dirname.substring(0, idx);
+  }
+
+  // Fallback to cwd for manual CLI invocation (e.g., npx sd-claude postinstall)
+  return process.cwd();
 }
 
 /** Checks if this is the simplysm monorepo with the same major version. */
@@ -107,16 +112,27 @@ function setupSettings(targetDir) {
   // statusLine: always overwrite
   settings["statusLine"] = { type: "command", command: "python .claude/sd-statusline.py" };
 
+  // Migrate: move root-level SessionStart to hooks.SessionStart
+  if (settings["SessionStart"] != null) {
+    settings["hooks"] = settings["hooks"] ?? {};
+    settings["hooks"]["SessionStart"] = [
+      ...(settings["hooks"]["SessionStart"] ?? []),
+      ...settings["SessionStart"],
+    ];
+    delete settings["SessionStart"];
+  }
+
   // SessionStart: ensure sd-session-start hook exists with correct config
+  settings["hooks"] = settings["hooks"] ?? {};
   const sdSessionEntry = {
     matcher: "startup|resume|clear|compact",
     hooks: [{ type: "command", command: "bash .claude/sd-session-start.sh" }],
   };
 
-  const sessionStart = settings["SessionStart"];
+  const sessionStart = settings["hooks"]["SessionStart"];
 
   if (sessionStart == null) {
-    settings["SessionStart"] = [sdSessionEntry];
+    settings["hooks"]["SessionStart"] = [sdSessionEntry];
   } else {
     const idx = sessionStart.findIndex((entry) =>
       entry.hooks?.some((hook) => hook.command.includes("sd-session-start")),