@simplysm/sd-claude 13.0.75 → 13.0.77

package/claude/refs/sd-code-conventions.md

@@ -19,6 +19,7 @@ Before using extension methods: Verify actual existence in `@simplysm/core-commo
 
 - Do not use `Async` suffix on function names — Async is the default
 - When both sync and async versions exist, use `Sync` suffix on the sync function
+- **Exception — extensions**: When adding an async version to an existing prototype (e.g., `Array`), follow the original naming convention. If the sync method already exists without a `Sync` suffix, use `Async` suffix for the async version.
 
 ```typescript
 // Good
@@ -27,8 +28,12 @@ function readFileSync() { ... }        // Sync version
 
 // Bad
 async function readFileAsync() { ... } // Async suffix prohibited
+
+// Exception — Array extension already has mapMany()
+Array.prototype.mapManyAsync = async function () { ... }  // OK
 ```
 
+
 ## File Naming
 
 - Auxiliary files (`types.ts`, `utils.ts`, etc.) must be prefixed with the main file name (e.g., `CrudSheet.types.ts`)
@@ -37,7 +42,7 @@ async function readFileAsync() { ... } // Async suffix prohibited
 ## JSDoc Convention
 
 - Not enforced — omit when code is self-explanatory
-- When written, use Korean
+- When written, use English
 
 ## Re-export Restriction
 
@@ -46,12 +51,105 @@ async function readFileAsync() { ... } // Async suffix prohibited
 
 ## index.ts Export Pattern
 
-- Large packages: `#region`/`#endregion` for sections + `//` for sub-groups
-- Small packages (≤10 exports): `//` comments only
+- Use `//` comments to group exports
 - Always `export *` (wildcard), never explicit `export type { ... } from "..."`
 
+## `#region` / `#endregion`
+
+- When splitting a large ts/tsx file has a bigger tradeoff than keeping it as-is, use `#region`/`#endregion` to organize sections within the file
+- Do not use in simple export files like index.ts
+
+## `any` vs `unknown` vs Generics
+
+Choose based on **what you do with the value**:
+
+| Type | When | Key rule |
+|------|------|----------|
+| `any` | Value is **passed through** without property access | No `.prop`, no method calls, no narrowing |
+| `unknown` | Value's properties **will be accessed** but type is unknown | Must narrow with type guard before any access |
+| Generic `<T>` | **Input/output type relationship** must be preserved | Caller's type flows through to return type |
+
+```typescript
+// any — pure pass-through, no property access
+function logAndStore(value: any): void {
+  console.log(value);   // OK: no property access
+  storage.push(value);  // OK: just forwarding
+}
+
+// unknown — will access properties, must narrow first
+function getName(data: unknown): string {
+  if (typeof data === "object" && data !== null && "name" in data) {
+    return String((data as { name: unknown }).name);
+  }
+  throw new Error("No name property");
+}
+
+// Generic — input type preserved in output
+function wrapValue<T>(value: T): { value: T } {
+  return { value };
+}
+```
+
+**any vs Generic for pass-through:** If the function only forwards a value without accessing it AND the caller does not need type preservation in the return, use `any`. If the caller needs the same type back (input→output relationship), use a generic.
+
 ## Type Safety for Public APIs
 
 - API changes must be detectable via **typecheck alone** — all affected usage sites must show compile errors
 - Public component props must support **IDE intellisense** (autocomplete, type hints)
-- Avoid `any` in public-facing types; use generics or specific union types instead
+- **No `Record<string, any>` for structured props** — define explicit interfaces so consumers get autocomplete
+
+```typescript
+// Bad — consumers get no autocomplete, changes are invisible
+interface TableProps {
+  columns: Record<string, any>;
+  onRowClick: Function;
+}
+
+// Good — changes to ColumnDef break consumers at compile time
+interface TableProps<TRow> {
+  columns: ColumnDef<TRow>[];
+  onRowClick?: (row: TRow) => void;
+}
+```
+
+## Forced Type Casting Prohibition
+
+- **`as unknown as X` is prohibited** — dangerous escape hatch that silences real type errors
+- **`as X` must be avoided** unless there is no alternative — when tempted, try these fixes first:
+
+| Type error situation | Fix (instead of `as`) |
+|---------------------|-----------------------|
+| Missing properties | Add them to the interface |
+| Type too wide | Use generics to propagate correctly |
+| Unknown shape | Type guard: `if ("prop" in obj)`, `instanceof` |
+| Multiple shapes | Discriminated union or overload |
+| Wrong at source | Fix the root cause, not the usage site |
+
+```typescript
+// Bad — casting hides the real problem
+const admin = user as unknown as AdminUser;
+
+// Bad — lazy cast instead of proper narrowing
+const name = (event as any).target.name;
+
+// Good — fix parameter type at the source
+function getAdminDashboard(admin: AdminUser): string { ... }
+
+// Good — narrow unknown with type guard
+function getNameFromEvent(event: unknown): string {
+  if (typeof event === "object" && event !== null && "target" in event) {
+    const target = event.target;
+    if (typeof target === "object" && target !== null && "name" in target) {
+      return String(target.name);
+    }
+  }
+  throw new Error("Invalid event structure");
+}
+```
+
+## Boolean Prop Defaults
+
+- Name boolean props so their default value is `false`
+- Prefer `hide*`, `disable*` patterns where the feature is ON by default
+- This avoids double-negation in JSX: `hideX={false}` is clearer than `showX={true}` when both mean "show X"
+- Exception: inherent HTML attributes like `draggable` may default to `true`

package/claude/refs/sd-solid.md

@@ -34,8 +34,17 @@
 
 All sub-components via dot notation only (`Parent.Child`).
 
-- Define `interface ParentComponent { Child: typeof ChildComponent }`
-- Assign `Parent.Child = ChildComponent;`
+- Export using `Object.assign` pattern:
+  ```ts
+  export const Select = Object.assign(SelectInnerComponent, {
+    Item: SelectItem,
+    Header: SelectHeader,
+    Action: SelectAction,
+    ItemTemplate: SelectItemTemplate,
+  });
+  ```
+- Do NOT declare a separate type or interface for the compound component (e.g., `SelectComponent`, `TabsComponent`)
+- Do NOT use type assertions on the export (e.g., `as SelectComponent`)
 - Don't export sub-components separately (export parent only)
 - UI elements → compound sub-components, non-rendering config (state, behavior, callbacks) → props
 
@@ -48,6 +57,8 @@ All sub-components via dot notation only (`Parent.Child`).
 - Default `rem`, use `em` for text-relative sizing (e.g., Icon)
 - Use `clsx()` with semantic grouping + `twMerge()` for conflict resolution
 - Before modifying styles: Read existing class patterns of the same component
+- **Class strings inline**: Do not extract class strings into separate variables — write them directly in the JSX return
+- **`*.styles.ts` files**: Tailwind class strings must be wrapped with `clsx()` for IntelliSense support
 
 ## Application View Naming (`client-*`)
 

package/claude/refs/sd-workflow.md

@@ -6,7 +6,7 @@
 ## Problem-Solving Principles
 
 - **Root cause first**: When encountering errors or unexpected behavior, always investigate the root cause before attempting a fix. Do not apply workarounds, hacks, or surface-level patches.
-- **No band-aid fixes**: Avoid techniques like suppressing errors, adding defensive checks to hide symptoms, or bypassing validation. These mask the real problem and create technical debt.
+- **No band-aid fixes**: Avoid techniques like suppressing errors, adding defensive checks to hide symptoms, bypassing validation, or inflating timeout values. These mask the real problem and create technical debt.
 - **Consider refactoring**: If the root cause reveals a design flaw or structural issue, propose a refactoring approach rather than working around it. A proper fix — even if larger in scope — is better than a fragile workaround.
 - **Trace the full chain**: Follow the error or issue through the entire call chain (caller -> callee -> dependencies) to understand why it happens, not just where it happens.
 - **When uncertain, ask**: If the root cause is unclear or the fix requires significant changes, discuss with the user before proceeding. Present findings and options rather than silently applying a quick fix.
@@ -16,6 +16,7 @@
 - Before creating new files: Glob/Read similar existing files to check structure and patterns
 - Before modifying functions/classes: Read the file to understand existing code style
 - When unsure about API/method usage: Check signatures in source code
+- **Always search the local codebase first.** Do not search the web or external docs until you have confirmed the answer is not in local code.
 - **If confidence is low, ask the user instead of writing code**
 
 ## Memory Policy

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

@@ -35,10 +35,27 @@ If a referenced file or document cannot be found, **stop immediately and ask the
 - **Do NOT comment on code outside the requested change.** This includes:
   - Listing issues you noticed but did not fix
   - Describing what you "left alone" or "did not change"
-  - "참고", "suggestions", "by the way", "note", "what I left alone"
+  - "reference", "suggestions", "by the way", "note", "what I left alone"
   - Any unsolicited observations about surrounding code quality
   - Only describe **what you changed** — nothing else
 
+### Analysis & Comparison
+
+- When analyzing, comparing, diffing, or auditing: **enumerate all items exhaustively**. Never provide a shallow summary — list every difference, even minor ones.
+  - Example: v12 vs v13 migration gap → list ALL API, type, pattern differences item by item
+
+### Direct Action Requests
+
+- When the user provides a specific action (e.g., "rename X to Y", "delete this file"), **execute it directly**. Do not route through skill agents or sub-agent workflows for trivial operations.
+
+## Worktree Rules
+
+All git worktrees MUST be created under the **`.worktrees/`** directory (project root). Never use `.claude/worktrees/` or any other location.
+
+- When using `isolation: "worktree"` on Agent tool calls, the worktree is created in `.worktrees/`.
+- **After work is complete, you MUST delete the worktree and its branch** before finishing. No worktree may be left behind.
+- Prefer using the **`/sd-worktree`** skill for worktree creation/deletion. It includes fixes for Claude Code's built-in worktree bugs.
+
 ## Asking Clarifying Questions
 
 When you need to ask the user a question, you MUST use the `AskUserQuestion` tool. Do NOT ask questions in plain text.

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

@@ -13,7 +13,7 @@ Determine the major version by the `version` field in `package.json`.
 
 | When                                             | Read this file                        |
 | ------------------------------------------------ | ------------------------------------- |
-| Writing or modifying code                        | `.claude/refs/sd-code-conventions.md` |
+| Writing, modifying, or reviewing code            | `.claude/refs/sd-code-conventions.md` |
 | Working with `.cache/` or Playwright screenshots | `.claude/refs/sd-directories.md`      |
 | Using `@simplysm/*` package APIs                 | `.claude/refs/sd-simplysm-docs.md`    |
 | Debugging, problem-solving, or planning approach | `.claude/refs/sd-workflow.md`         |

package/claude/sd-statusline.js

@@ -8,6 +8,8 @@ import { stdin } from "process";
 
 const STDIN_TIMEOUT_MS = 5000;
 const FETCH_TIMEOUT_MS = 3000;
+const CACHE_TTL_MS = 120_000; // 2 minutes
+const CACHE_PATH = path.join(os.homedir(), ".claude", "usage-api-cache.json");
 
 //#endregion
 
@@ -75,16 +77,49 @@ function getOAuthToken() {
 }
 
 /**
- * Fetch Anthropic API usage information using OAuth token.
+ * Read cached usage data from local file.
+ * @returns {{ data: object, timestamp: number } | undefined}
+ */
+function readCache() {
+  try {
+    if (!fs.existsSync(CACHE_PATH)) return undefined;
+    const content = fs.readFileSync(CACHE_PATH, "utf-8");
+    return JSON.parse(content);
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * Write usage data to local cache file.
+ * @param {object} data
+ */
+function writeCache(data) {
+  try {
+    fs.writeFileSync(CACHE_PATH, JSON.stringify({ data, timestamp: Date.now() }), "utf-8");
+  } catch {
+    // ignore write errors
+  }
+}
+
+/**
+ * Fetch Anthropic API usage information using OAuth token, with 1-minute cache.
  * @param {string} token - OAuth access token
+ * @param {string} version - Claude Code version
  * @returns {Promise<{
- *   seven_day?: {utilization?: number, resets_at?: string},  // 7-day usage
- *   daily?: {utilization?: number, resets_at?: string},       // daily usage
- *   five_hour?: {utilization?: number, resets_at?: string},   // 5-hour usage
- *   extra_usage?: {is_enabled?: boolean, monthly_limit?: number | null, used_credits?: number}  // extra usage
+ *   seven_day?: {utilization?: number, resets_at?: string},
+ *   daily?: {utilization?: number, resets_at?: string},
+ *   five_hour?: {utilization?: number, resets_at?: string},
+ *   extra_usage?: {is_enabled?: boolean, monthly_limit?: number | null, used_credits?: number}
  * } | undefined>}
  */
-async function fetchUsage(token) {
+async function fetchUsage(token, version) {
+  // Return cached data if still valid
+  const cache = readCache();
+  if (cache != null && Date.now() - cache.timestamp < CACHE_TTL_MS) {
+    return cache.data;
+  }
+
   try {
     const controller = new AbortController();
     const timeout = setTimeout(() => controller.abort(), FETCH_TIMEOUT_MS);
@@ -92,7 +127,8 @@ async function fetchUsage(token) {
     const response = await fetch("https://api.anthropic.com/api/oauth/usage", {
       headers: {
         "Authorization": `Bearer ${token}`,
-        "anthropic-beta": "oauth-2025-04-20",
+        "Accept": "application/json",
+        'anthropic-beta': 'oauth-2025-04-20'
       },
       signal: controller.signal,
     });
@@ -100,18 +136,23 @@ async function fetchUsage(token) {
     clearTimeout(timeout);
 
     if (!response.ok) {
+      // API failed — update timestamp to prevent retry for TTL duration
+      writeCache(cache?.data ?? {});
       return undefined;
     }
 
     const data = await response.json();
 
-    // Validate response structure
     if (data == null || typeof data !== "object") {
+      writeCache(cache?.data ?? {});
       return undefined;
     }
 
+    writeCache(data);
     return data;
   } catch {
+    // Network error — update timestamp to prevent retry for TTL duration
+    writeCache(cache?.data ?? {});
     return undefined;
   }
 }
@@ -172,6 +213,7 @@ function formatTimeRemaining(isoDate) {
  * @property {{display_name?: string}} [model] - Model information
  * @property {{context_window_size?: number, remaining_context_tokens?: number, current_usage?: {input_tokens?: number, output_tokens?: number, cache_creation_input_tokens?: number, cache_read_input_tokens?: number}}} [context_window] - Context window information
  * @property {{tokens_used?: number, tokens_limit?: number}} [weekly_token_usage] - Weekly token usage (fallback)
+ * @property {string} [version] - Claude Code version
  */
 
 /**
@@ -212,7 +254,7 @@ async function main() {
   let extraUsage = "";
 
   if (token != null) {
-    const usageResponse = await fetchUsage(token);
+    const usageResponse = await fetchUsage(token, input.version ?? "unknown");
     if (usageResponse != null) {
       // Use daily or five_hour
       const dailyData = usageResponse.daily ?? usageResponse.five_hour;

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

@@ -8,32 +8,97 @@ model: sonnet
 
 ## Overview
 
-Compare a library/module's public API names against industry standards and review internal consistency, producing a standardization report. **Analysis only — no code modifications.**
+Compare a library/module's public API names against industry standards and review internal consistency, producing a standardization report. Uses **sd-explore** to extract the API surface, then dispatches research agents for industry comparison.
+
+**Analysis only — no code modifications.**
+
+## Principles
+
+- **Breaking changes are irrelevant**: Do NOT dismiss findings because renaming would cause a breaking change.
+- **Internal consistency first**: Internal naming consistency takes priority over external standards.
+
+## Usage
+
+- `/sd-api-name-review packages/solid` — full naming review
+- `/sd-api-name-review packages/orm-common` — review specific package
+- `/sd-api-name-review` — if no argument, ask the user for the target path
 
 ## Target Selection
 
-1. If args contain a path, use that path
-2. Otherwise, ask the user for the target path
+- With argument: review source code at the given path
+- Without argument: ask the user for the target path
+
+**Important:** Review ALL source files under the target path. Do not use git status or git diff to limit scope.
+
+## Workflow
+
+### Step 1: Prepare Context
+
+Read these files:
+- `CLAUDE.md` — project overview
+- `.claude/rules/sd-refs-linker.md` — reference guide
+- Target's `package.json` — version (v12/v13)
 
-## Phase 1: API Extraction
+Based on version and target, read all applicable reference files (e.g., `sd-code-conventions.md`, `sd-solid.md`).
 
-Use an Explore agent to extract the target's public API surface:
+Keep the collected conventions in memory — they will inform the analysis in later steps.
 
+### Step 2: API Extraction (via sd-explore)
+
+Follow the **sd-explore** workflow to extract the target's public API surface.
+
+**sd-explore input:**
+
+- **Target path**: the review target directory
+- **Name**: `api-name-review`
+- **File patterns**: `**/*.ts`, `**/*.tsx` (exclude `node_modules`, `dist`)
+- **Analysis instructions**:
+
+"For each file, extract its public API surface:
 - All exported identifiers (functions, classes, types, constants, etc.)
 - Names and types of user-facing parameters/options/config
 - Naming pattern classification (prefixes, suffixes, verb/adjective/noun usage, abbreviations, etc.)
 
-## Phase 2: Industry Standard Research
+Output format:
+```
+# API Surface: [directory names]
 
-Based on Phase 1 results, determine comparison targets and perspectives:
+## Exports
+- `path/to/file.ts` — `exportName`: type (function/class/type/const), signature summary
+
+## Naming Patterns
+- Pattern: description (e.g., 'create-' prefix for factory functions)
+- Examples: list of identifiers using this pattern
+```
+"
+
+### Step 3: Industry Standard Research
+
+Based on Step 2 results:
 
 1. Identify **recurring naming patterns** from the extracted API
 2. Determine the target's domain and tech stack to **select comparable libraries**
-3. Use **parallel agents** to web-search/fetch official docs for each library, investigating naming conventions for the same pattern categories
+3. Dispatch **parallel agents** to web-search/fetch official docs for each comparable library, investigating naming conventions for the same pattern categories
+
+Each research agent receives:
 
-## Phase 3: Comparative Analysis & Report
+```
+Research naming conventions in [library name] for these pattern categories:
+[list of patterns from Step 2]
 
-Cross-compare Phase 1 and Phase 2 results to produce the report.
+For each pattern, document:
+- What naming convention the library uses
+- Specific examples from the API
+- Any documented rationale for the convention
+
+Write results to: .tmp/api-name-review/research-{library_name}.md
+```
+
+### Step 4: Comparative Analysis & Verification
+
+Cross-compare Step 2 (API surface) and Step 3 (industry research) results.
+
+Classify each naming pattern:
 
 | Priority | Criteria                                               |
 | -------- | ------------------------------------------------------ |
@@ -42,8 +107,48 @@ Cross-compare Phase 1 and Phase 2 results to produce the report.
 | **P2**   | Better industry term exists (optional)                 |
 | **Keep** | Already aligned with standards                         |
 
-Each item includes: current name, recommended change, rationale (usage patterns per library).
+**MANDATORY: Read actual code for EVERY finding.** For each finding, `Read` the file at the referenced location before finalizing. Do NOT rely on explore descriptions alone — verify against the actual code.
+
+Each finding includes: current name, recommended change, rationale (usage patterns per library).
+
+### Step 5: Report & User Confirmation
+
+Present **Keep** items to the user as a summary.
+
+Then present each **P0/P1/P2** finding to the user **one at a time**, ordered by priority (P0 → P1 → P2).
+
+For each finding, explain:
+1. **What the problem is** — the current name and why it's misaligned or inconsistent
+2. **How it could be fixed** — recommended name(s) with rationale from surveyed libraries
+3. **Ask**: address this or skip?
+
+Collect only findings the user confirms. If the user skips all findings, report that and end.
+
+### Step 6: Brainstorm Handoff
+
+Invoke **sd-brainstorm** with all user-confirmed findings as context:
+
+_
+"Design naming changes for the following review findings.
+
+**For each finding, you MUST:**
+1. Review it thoroughly — examine the code, understand the context, assess the real impact
+2. If any aspect is unclear or ambiguous, ask the user (one question at a time, per brainstorm rules)
+3. If a finding has low cost-benefit (adds complexity for marginal gain, pure style preference, scope too small), drop it. After triage, briefly list all dropped findings with one-line reasons (no user confirmation needed).
+4. For findings worth fixing, explore approaches and design solutions
+
+Findings that survive your triage become the design scope. Apply your normal brainstorm process (gap review → approaches → design presentation) to the surviving findings as a group.
+
+<include all confirmed findings with their priority, file:line, current name, recommended name, and rationale>"
+
+sd-brainstorm then owns the full cycle: triage (with user input as needed) → design.
 
-## Completion Criteria
+## Common Mistakes
 
-Present the report to the user. No code modifications.
+| Mistake | Fix |
+|---------|-----|
+| Using git diff to limit scope | Review ALL source files under target |
+| Skipping context preparation | Always read conventions and refs before analysis |
+| Skipping verification | Always verify findings against actual code |
+| Dismissing findings due to breaking changes | Breaking changes are irrelevant — report the naming issue |
+| Not writing research results to files | Research agents MUST write to disk — prevents context bloat |

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

@@ -14,12 +14,36 @@ Start by understanding the current project context, then ask questions one at a
 ## The Process
 
 **Understanding the idea:**
-- Check out the current project state first (files, docs, recent commits)
+- Check out the current project state first (files, docs, recent commits).
 - Ask questions one at a time to refine the idea
 - Prefer multiple choice questions when possible, but open-ended is fine too
 - Only one question per message - if a topic needs more exploration, break it into multiple questions
 - Focus on understanding: purpose, constraints, success criteria
 
+**When a main design document is provided as context:**
+
+```mermaid
+flowchart TD
+    A{"Main design with<br>section plan in context?"}
+    A -->|no| B[Normal brainstorm]
+    A -->|yes| C{Section specified?}
+    C -->|no| D["Show section progress<br>Ask which section<br>(suggest next incomplete)"]
+    C -->|yes| E{"Prerequisites<br>complete?"}
+    E -->|yes| F[Proceed with section]
+    E -->|no| G["Warn prerequisites incomplete<br>Ask: proceed anyway<br>or complete first?"]
+    G -->|"user: proceed"| F
+```
+
+When proceeding with a section:
+
+1. **Read the main design** — understand goals, overall structure, and the target section's scope
+2. **Read actual code** — check the current codebase state for what previous sections have built. Reference the **actual code**, NOT previous section design documents. Code may have diverged from earlier designs during implementation.
+3. **Scope the brainstorm** — limit questions, gap review, approaches, and design presentation to the target section only. Do not re-question decisions already established in the main design.
+4. **Conflict detection** — if the main design's direction conflicts with the actual code state, alert the user and ask for direction before proceeding.
+5. After the design is complete, save as `docs/plans/YYYY-MM-DD-<topic>-section-N-design.md`
+6. Update the main design document: mark the section `[ ]` → `[x]` in the section plan
+7. Commit both files, then proceed to the normal **Next Steps Guide** (Path A/B)
+
 **Gap review loop:**
 
 When you think you've asked enough, **STOP and run a gap review before moving on.**
@@ -69,12 +93,63 @@ If your first gap review shows all ✅:
 - Present options conversationally with your recommendation and reasoning
 - Lead with your recommended option and explain why
 
-**Presenting the design:**
-- Once you believe you understand what you're building, present the design
-- Break it into sections of 200-300 words
-- Ask after each section whether it looks right so far
-- Cover: architecture, components, data flow, error handling, testing
-- Be ready to go back and clarify if something doesn't make sense
+**Scale assessment:**
+
+After the approach is selected, assess scale (file count, logic complexity, number of distinct subsystems, scope of impact):
+
+```mermaid
+flowchart TD
+    A{"Assess design scale"}
+    A -->|manageable| B["Proceed to<br>After the Design<br>(Path A/B)"]
+    A -->|large| C["Propose to user:<br>proceed as-is OR<br>split into sections"]
+    C --> D{"User choice?"}
+    D -->|"proceed as-is"| B
+    D -->|split| E["Propose 2-3 section<br>division approaches<br>(by feature/layer/dependency)"]
+    E -->|"user selects"| F["Append section plan<br>to design doc<br>Save + commit"]
+    F --> G["Show section guide<br>Brainstorm ENDS"]
+```
+
+**How to present the split proposal:**
+
+When proposing the split to the user, you MUST clearly explain what "section split" means:
+
+- **Section split** = the design document is divided into sections, and each section goes through its own **separate brainstorm → plan → plan-dev → check → commit cycle**.
+- This is NOT about implementation phasing (doing some changes before others). It's about breaking the design work itself into independently deliverable chunks.
+- Explain: "Splitting into sections means each section goes through its own brainstorm → plan → plan-dev cycle. Complete and commit one section before moving to the next."
+- Contrast with: "Proceeding as-is means this single design document goes straight to plan → plan-dev."
+
+**Section plan format** (append to existing design content as-is):
+
+```markdown
+---
+
+## Section Plan
+
+- [ ] Section 1: <name> — <scope summary>
+- [ ] Section 2: <name> — <scope summary> (after section 1)
+- [ ] Section 3: <name> — <scope summary> (after section 1, 2)
+```
+
+**Section guide** (shown instead of Path A/B, in user's configured language):
+
+```
+Design has been split into sections.
+
+Main design: docs/plans/YYYY-MM-DD-<topic>-design.md
+
+Section progress:
+- [ ] Section 1: <name>
+- [ ] Section 2: <name> (after section 1)
+- [ ] Section 3: <name> (after section 1, 2)
+
+Run each section in order:
+  sd-brainstorm docs/plans/YYYY-MM-DD-<topic>-design.md section 1
+
+After each section's brainstorm completes, you can choose Path A/B
+to run plan → plan-dev → check → commit.
+```
+
+Do NOT auto-proceed to any section.
 
 ## After the Design
 
@@ -137,5 +212,4 @@ You can start from any step or skip steps as needed.
 - **Multiple choice preferred** - Easier to answer than open-ended when possible
 - **YAGNI ruthlessly** - Remove unnecessary features from all designs
 - **Explore alternatives** - Always propose 2-3 approaches before settling
-- **Incremental validation** - Present design in sections, validate each
 - **Be flexible** - Go back and clarify when something doesn't make sense