lee-spec-kit 0.8.8 → 0.9.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "lee-spec-kit",
-  "version": "0.8.8",
+  "version": "0.9.1",
   "description": "Document-centered harness engineering toolkit for AI agent development",
   "type": "module",
   "bin": {
@@ -13,18 +13,6 @@
     "templates",
     "assets"
   ],
-  "scripts": {
-    "build": "tsup",
-    "dev": "tsup --watch",
-    "lint": "eslint src",
-    "lint:test": "eslint tests",
-    "typecheck": "tsc --noEmit",
-    "typecheck:test": "tsc -p tsconfig.tests.json --noEmit",
-    "test": "pnpm build && vitest run",
-    "test:race": "pnpm build && vitest run tests/race.test.mjs",
-    "format": "prettier --write .",
-    "prepublishOnly": "pnpm build"
-  },
   "keywords": [
     "docs",
     "template",
@@ -66,5 +54,15 @@
     "typescript": "^5.9.3",
     "vitest": "^4.0.18"
   },
-  "packageManager": "pnpm@10.7.0"
-}
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "lint": "eslint src",
+    "lint:test": "eslint tests",
+    "typecheck": "tsc --noEmit",
+    "typecheck:test": "tsc -p tsconfig.tests.json --noEmit",
+    "test": "pnpm build && vitest run",
+    "test:race": "pnpm build && vitest run tests/race.test.mjs",
+    "format": "prettier --write ."
+  }
+}

package/templates/en/common/README.md

@@ -16,7 +16,7 @@ npx lee-spec-kit docs get agents --json
 - Use workspace-scoped `AGENTS.md`, official Codex hooks, and the active feature docs as the default runtime path.
 - Resolve the active feature, then treat `spec.md`, `plan.md`, `tasks.md`, and `decisions.md` as the working SSOT.
 - Ask for approval only at documented workflow checkpoints and before remote or destructive actions.
-- Use `npx lee-spec-kit commit-audit --json` before `git commit` when staged docs paths need validation.
+- Use `npx lee-spec-kit commit-audit --json` before `git commit` for staged docs-path checks and canonical Feature-scoped commit validation.
 - Use `npx lee-spec-kit workflow-audit --json` before stopping when code or feature docs changed.
 - If `isLeeSpecKitProject: false`, skip lee-spec-kit-specific flow and continue with normal workflow.
 
@@ -30,13 +30,29 @@ npx lee-spec-kit docs get agents --json
 
 ## Directory Structure
 
-| Path              | Purpose               | Key Documents |
-| ----------------- | --------------------- | ------------- |
+| Path              | Purpose               | Key Documents                                                                                                      |
+| ----------------- | --------------------- | ------------------------------------------------------------------------------------------------------------------ |
 | `docs/agents/`    | Agent operating rules | `custom.md`, `constitution.md` (engine-managed guides are fetched via `npx lee-spec-kit docs get <doc-id> --json`) |
-| `docs/prd/`       | Product requirements  | Project-specific |
-| `docs/designs/`   | Design references     | `README.md` (links/guidelines/references) |
-| `docs/ideas/`     | Ideas / to-dos        | `README.md` (Idea → Feature promotion rules) |
-| `{{featurePath}}` | Feature documentation | `{feature-id}/spec.md`, `plan.md`, `tasks.md`, `decisions.md` |
+| `docs/prd/`       | Product requirements  | Project-specific                                                                                                   |
+| `docs/designs/`   | Design references     | `README.md` (links/guidelines/references)                                                                          |
+| `docs/ideas/`     | Ideas / to-dos        | `README.md` (Idea → Feature promotion rules)                                                                       |
+| `{{featurePath}}` | Feature documentation | `{feature-id}/spec.md`, `plan.md`, `tasks.md`, `decisions.md`                                                      |
+
+---
+
+## Document Routing
+
+| Document content                                                      | Location                            |
+| --------------------------------------------------------------------- | ----------------------------------- |
+| Product requirements, user stories, and product roadmaps              | `docs/prd/`                         |
+| System architecture overviews shared by multiple Features             | `docs/prd/*-overview.md`            |
+| Durable architecture principles                                       | `docs/agents/constitution.md`       |
+| Technical research and candidate comparisons before Feature promotion | The relevant `docs/ideas/I###-*.md` |
+| Implementation design for an active Feature                           | That Feature's `plan.md`            |
+| Technical choices, alternatives, and trade-offs                       | That Feature's `decisions.md`       |
+| Screens, Figma, design systems, and UI flows                          | `docs/designs/`                     |
+
+Keep product roadmaps in `prd/`, but manage implementation sequencing and work plans in the active Feature's `plan.md` and `tasks.md`. The `designs/` directory is reserved for UX and visual design, not technical design.
 
 ---
 
@@ -114,13 +130,24 @@ When you run `lee-spec-kit init`, it creates `.lee-spec-kit.json` in the docs ro
 - `docsRepo` ("embedded" | "standalone"): How docs are managed
 - `pushDocs` (boolean, optional): Only written when `docsRepo: "standalone"` (whether to push to remote)
 - `docsRemote` (string, optional): Only written when `pushDocs: true` (remote repo URL)
+- `workflow.prePrReview.reviewer` (object): Pre-PR subagent execution settings
+  - `type`: currently only `"subagent"` is supported
+  - `model`: `"inherit"` or a model name supported by the runtime
+  - `reasoningEffort`: `low | medium | high | xhigh | max | ultra`
+  - `onUnavailable`: `inherit | error` when the requested model is unavailable
+- `workflow.baseBranch` (string): branch that receives a completed local Feature
+- `workflow.completionStrategy` (`"local-ff" | "local-squash" | "none"`): fast-forward, create one verified squash commit, or explicitly finish without integration
+- `workflow.deleteFeatureBranchAfterMerge` (boolean): delete the integrated local Feature branch after cleanup; remote branches are never deleted
+- `workflow.postMergeChecks` (array): structured commands run from the base branch after local integration, for example `{ "command": "pnpm", "args": ["test"] }`
 - `approval` (object, optional): optional approval-checkpoint metadata for repo policy and custom validators
   - The Codex-native default path still asks at documented checkpoints and before remote/destructive actions first.
   - Legacy runtime consumed this field directly; keep it only when you intentionally want category-based checkpoint metadata.
   - Current default:
     - `mode: "category"`
     - `default: "skip"`
-    - `requireCheckCategories: ["spec_approve", "implementation_approve"]`
+    - `requireCheckCategories: ["spec_approve", "implementation_approve", "local_merge"]`
+  - In a `local-ff` or `local-squash` workflow, `implementation_approve` approves the completed implementation and `local_merge` separately authorizes the configured integration, post-merge checks, managed-worktree removal, and configured local Feature-branch deletion.
+  - Remove `local_merge` from `requireCheckCategories` only when the implementation approval should authorize the remaining local completion flow without another checkpoint.
   - Approval token: `A`
   - Accepted replies: `A`, `A OK`
 - `allowedDocsEntries` (object, optional): Allowlist non-standard top-level docs entries so they are not treated as unmanaged docs
@@ -136,17 +163,35 @@ When you run `lee-spec-kit init`, it creates `.lee-spec-kit.json` in the docs ro
   "lang": "en",
   "createdAt": "{{date}}",
   "docsRepo": "embedded",
+  "workflow": {
+    "mode": "local",
+    "baseBranch": "main",
+    "completionStrategy": "local-ff",
+    "deleteFeatureBranchAfterMerge": true,
+    "postMergeChecks": [],
+    "prePrReview": {
+      "evidenceMode": "path_required",
+      "reviewer": {
+        "type": "subagent",
+        "model": "inherit",
+        "reasoningEffort": "high",
+        "onUnavailable": "inherit"
+      }
+    }
+  },
   "allowedDocsEntries": {
     "dirs": ["plans"]
   },
   "approval": {
     "mode": "category",
     "default": "skip",
-    "requireCheckCategories": ["spec_approve", "implementation_approve"]
+    "requireCheckCategories": ["spec_approve", "implementation_approve", "local_merge"]
   }
 }
 ```
 
+New local projects use `local-ff`. Choose `local-squash` to create one base-branch commit while preserving the source Feature tip under an internal `refs/lee-spec-kit/integrations/*` ref for task-checkpoint evidence. During `update`, an existing local project with no explicit `completionStrategy` receives `none` so an upgrade does not unexpectedly merge its current branch. Set it to `local-ff` or `local-squash` deliberately when ready.
+
 ```json
 {
   "projectName": "{{projectName}}",
@@ -159,7 +204,7 @@ When you run `lee-spec-kit init`, it creates `.lee-spec-kit.json` in the docs ro
   "approval": {
     "mode": "category",
     "default": "skip",
-    "requireCheckCategories": ["spec_approve", "implementation_approve"]
+    "requireCheckCategories": ["spec_approve", "implementation_approve", "local_merge"]
   }
 }
 ```

package/templates/en/common/agents/agents.md

@@ -27,23 +27,48 @@ This document defines workflow policy, not a custom runtime loop.
 - After reading the active feature docs, run `npx lee-spec-kit workflow-stage <featureRef> --json` and follow only that `nextAction`.
 - If `workflow-stage --json` also returns `primaryActionLabel` and `actionOptions`, treat `primaryActionLabel` as the default option label and present the exact `actionOptions[*].reply` tokens to the user.
 
+## Document Routing
+
+| Content                                                   | SSOT location                       |
+| --------------------------------------------------------- | ----------------------------------- |
+| Product requirements, user stories, and product roadmaps  | `docs/prd/`                         |
+| System architecture overviews shared by multiple Features | `docs/prd/*-overview.md`            |
+| Durable architecture principles                           | `docs/agents/constitution.md`       |
+| Pre-Feature technical research and candidate comparison   | The relevant `docs/ideas/I###-*.md` |
+| Active Feature implementation design                      | That Feature's `plan.md`            |
+| Technical choices, alternatives, and trade-offs           | That Feature's `decisions.md`       |
+| Screens, Figma, design systems, and UI flows              | `docs/designs/`                     |
+
+- Do not use `docs/designs/` for system architecture, data/API design, technical research, or implementation plans.
+- Follow the detailed routing rules in `docs/README.md`.
+
+## Optional UI/UX Design Policy
+
+- Only when the user request explicitly mentions a design system, UI/visual redesign, design consistency, shared UI/component-library consolidation, branding/theme/token redesign, or implementation from Figma/design images, read and apply `npx lee-spec-kit docs get ui-ux-design --json`.
+- Do not apply this policy merely because the target is web/frontend, to a non-UI/backend Feature, or to a simple bug fix unrelated to durable design rules.
+- This is optional guidance, not a `requiredDocs` entry or workflow approval gate.
+
 ## Execution Rules
 
 - lee-spec-kit owns docs structure, workflow stages, and validators.
 - Codex owns the execution loop, tool usage, and hook lifecycle.
 - Do not start implementation unless `workflow-stage --json` reports `stage === "implementation"` and `implementationAllowed === true`.
+- When `workflow-stage --json` returns `nextAction.category: pre_pr_review` with `executor: subagent`, run a fresh, read-only subagent review using the returned `model`, `reasoningEffort`, and `onUnavailable` policy. Do not select or require a named review skill.
+- The Pre-PR review subagent returns findings without modifying code. The main agent remediates findings and records reviewer metadata and the final decision as evidence.
 - Treat spec/plan/tasks approval, issue creation, and branch creation as hard gates before implementation.
 - In standalone mode, do not hand-write `git worktree add`; run the exact `nextAction.command` from `workflow-stage` so the managed workspace path, stale directory cleanup, and `.env`/`.env.*` copy step stay consistent.
+- In local mode, do not stop after implementation approval. Follow the exact `local merge` and `local cleanup` commands returned by `workflow-stage` until verified integration and cleanup produce `done`.
+- In a `local-ff` or `local-squash` workflow, keep implementation approval and local merge approval distinct when `local_merge` is required: the first accepts the implementation, and the second authorizes the configured integration strategy, post-merge checks, and local cleanup.
 - Keep docs synced with code changes in the same turn whenever behavior or scope changes.
-- Use `npx lee-spec-kit commit-audit --json` before `git commit` when staged docs paths need validation.
+- Use `npx lee-spec-kit commit-audit --json` before `git commit`; Feature-scoped commits use `#123` when an Issue is linked and the stable Feature ID such as `F027` for issue-less local workflows.
 - Use `npx lee-spec-kit workflow-audit --json` as the default end-of-turn docs sync check.
 
 ## Approval Rules
 
-| Current action (examples) | What to share |
-| --- | --- |
-| Issue creation | Before `npx lee-spec-kit github issue <featureRef> --create` |
-| PR creation | Before `npx lee-spec-kit github pr <featureRef> --create` |
+| Current action (examples) | What to share                                                |
+| ------------------------- | ------------------------------------------------------------ |
+| Issue creation            | Before `npx lee-spec-kit github issue <featureRef> --create` |
+| PR creation               | Before `npx lee-spec-kit github pr <featureRef> --create`    |
 
 - Ask the user for approval at documented workflow checkpoints and before remote or destructive actions.
 - If `workflow-stage --json` says `approvalRequired === true`, stop and ask the user at that checkpoint.

package/templates/en/common/agents/git-workflow.md

@@ -6,11 +6,11 @@ Rules for AI agents to automate Git/GitHub operations.
 
 ## Core Concepts
 
-| Concept          | GitHub Mapping | Description                     |
-| ---------------- | -------------- | ------------------------------- |
-| Feature          | GitHub Issue   | Feature-level work unit         |
-| Task             | Commit         | Individual implementation unit  |
-| Feature Complete | Pull Request   | Create PR on feature completion |
+| Concept          | GitHub Workflow | Local Workflow | Description                     |
+| ---------------- | --------------- | -------------- | ------------------------------- |
+| Feature          | GitHub Issue    | Feature ID     | Feature-level work unit         |
+| Task             | Commit          | Commit         | Individual implementation unit  |
+| Feature Complete | Pull Request    | Local merge    | Feature completion integration  |
 
 ---
 
@@ -50,10 +50,27 @@ main
 
 ### Format
 
-```
+Use exactly one canonical Feature scope. Do not invent alternate scope forms.
+
+```text
+# Feature linked to a GitHub Issue
 {type}(#{issue}): {description}
+
+# Issue-less local Feature
+{type}({featureId}): {description}
+```
+
+Examples:
+
+```text
+feat(#123): implement user auth
+docs(#123): clarify auth spec
+feat(F027): implement notification settings
+docs(F027): update notification docs
 ```
 
+For local Features, the scope is the stable Feature ID (`F027`), not the full folder ref (`F027-notification-settings`). Feature-scoped commits without a scope, such as `docs: F027 ...`, are not canonical.
+
 ### Type List
 
 | Type       | Description   | Example                               |
@@ -115,15 +132,17 @@ git worktree add .worktrees/feat-{issue-number}-{feature-name} feat/{issue-numbe
 
 #### Standalone Mode Commit Guide
 
+Use the scope selected by the workflow: `#123` when an Issue is linked, otherwise the local Feature ID such as `F027`.
+
 1. **Project Commit** (If code changed)
 
    ```bash
-   git commit -m "feat(#123): implement feature"
+   git commit -m "feat(F027): implement feature"
    ```
 
 2. **Docs Commit** (If docs changed - **Run in Docs Repo**)
    ```bash
-   git commit -m "docs(#123): update feature docs"
+   git commit -m "docs(F027): update feature docs"
    ```
 
 > 💡 **Core Rule**: At task completion, **all changed repositories** must be committed.

package/templates/en/common/agents/skills/create-pr.md

@@ -17,7 +17,9 @@ Execution-state SSOT is the feature-local `pr.md`.
 
 ## Pre-PR Baseline Checklist (`builtin-checklist`)
 
-Always run this checklist in Pre-PR review. Treat it as the minimum baseline, then use review skills for deeper inspection when available.
+The Pre-PR subagent must always run this minimum baseline. Do not depend on a named review skill.
+
+When `workflow-stage --json` returns `nextAction.executor: subagent`, delegate the review to a fresh, read-only subagent. `model: inherit` means inheriting the current model; any other value is used as the subagent model override. If that model is unavailable, follow `onUnavailable` (`inherit` or `error`).
 
 1. Review alignment with `spec.md` / `plan.md` / `tasks.md` and confirm implementation still matches the original goal.
 2. Inspect regression, exception handling, critical/security risks, side effects, user flow impact, and release readiness.
@@ -31,6 +33,8 @@ Always run this checklist in Pre-PR review. Treat it as the minimum baseline, th
 10. `Pre-PR Decision` must use `decision: approve|changes_requested|blocked ...` (or `결정: ...`).
 11. Ensure the final decision is `approve` before moving to PR creation.
 
+The review artifact must record the actual `executor`, `model`, `reasoningEffort`, reviewed commit/diff scope, findings, and final decision. The review subagent must not modify code; the main agent owns finding remediation and documentation updates.
+
 ---
 
 ## Steps

package/templates/en/common/agents/skills/split-feature.md

@@ -16,7 +16,8 @@ Use this guide when one Feature/Issue becomes too large to review safely.
 Notes:
 
 - Keep one issue only for small, tightly coupled work.
-- Preserve "Feature = Issue" by creating multiple linked child issues/features.
+- In GitHub workflow, create one linked child Issue for each child Feature.
+- In local workflow, track each child Feature by its own Feature ID without requiring Issues.
 
 ---
 

package/templates/en/common/agents/ui-ux-design.md

@@ -0,0 +1,128 @@
+# UI/UX Design Documentation Policy
+
+This optional policy separates durable design rules from Feature-specific visual material in UI/UX work.
+It does not add a workflow stage or approval gate.
+
+---
+
+## Activation Conditions
+
+Apply this policy **only when the user request explicitly includes** one of these intents:
+
+- a design system
+- a UI redesign or visual redesign
+- design consistency
+- shared UI or component-library consolidation
+- branding or theme/token redesign
+- implementation from Figma or design images
+
+Do not apply it merely because:
+
+- the target component is web/frontend
+- the Feature is backend or otherwise non-UI
+- the request is a simple bug fix that does not change durable design rules
+- the change is a local style adjustment to one existing component
+
+If the signal is ambiguous, do not create design docs; use only the active Feature docs.
+
+## Recommended Structure
+
+When an activation condition is met and durable rules or visual references are actually needed, use only the necessary parts of this structure:
+
+```text
+docs/designs/
+├── README.md
+├── design-system.md
+├── <feature-visual-brief>.md
+└── assets/
+    └── <feature-name>/
+```
+
+- Do not create every file preemptively.
+- If `docs/designs/design-system.md` already exists, reference or update it instead of creating a replacement.
+- Do not make one `design.md` per Feature the default.
+- Do not migrate an existing project's document structure or make these documents a required gate.
+
+## Document Responsibilities
+
+### `docs/designs/design-system.md`
+
+Record durable meaning and usage rules shared by multiple Features:
+
+- semantic color tokens
+- typography
+- spacing and layout
+- radius, border, and shadow
+- shared components and variants
+- states such as loading, empty, error, and processing
+- responsive rules
+- accessibility and motion rules
+- content voice
+- design-system change, deprecation, and synchronization policy
+
+Use this frontmatter:
+
+```yaml
+---
+lee-spec-kit:
+  kind: design-system
+  scope: project
+---
+```
+
+### `docs/designs/<feature-visual-brief>.md`
+
+Record the UX direction and visual references for one Feature:
+
+- original Figma URLs and any necessary repository snapshots
+- design images and reference screens
+- intent and key states for each screen or flow
+- gaps between the current data/API contract and the design
+- applicable `design-system.md` rules and Feature-specific interpretation
+
+Use `kind: ux-design` or `kind: visual-reference` with `scope: project`, as appropriate. This document is the Feature's visual reference authority; it does not replace the authorities for requirements, implementation planning, or technical decisions.
+
+### Feature `spec.md`
+
+- Keep user requirements and acceptance criteria here.
+- Link the design system and visual brief through optional `Design Refs` using project-root paths.
+
+### Feature `plan.md`
+
+- Record the change surface for token/theme files, shared components, routes/screens, and Storybook or an equivalent workbench.
+- Explain how design rules map to executable code and tests.
+
+### Feature `decisions.md`
+
+- Record why the design system changed or why an exception exists.
+- Include the exception scope, affected rule, and removal condition.
+
+## Executable Authorities and Responsibility Split
+
+Do not treat `design-system.md` as the only source of truth.
+
+| Surface                           | Responsibility                                       |
+| --------------------------------- | ---------------------------------------------------- |
+| `docs/designs/design-system.md`   | Meaning, intent, and usage rules                     |
+| CSS theme/globals or token files  | Executed token values                                |
+| Shared UI directory               | Executed component APIs and variant contracts        |
+| Storybook or equivalent workbench | Executable examples of variants and states           |
+| Feature `decisions.md`            | Exceptions, change rationale, and removal conditions |
+
+The document explains meaning; code and the workbench prove the executable contract.
+
+## Synchronization Rules
+
+- When a Feature changes `design-system.md`, use the same `tasks.md` task to name the affected design docs, token/theme files, shared UI, Storybook/workbench examples, and relevant verification.
+- Do not force edits to an unaffected surface, but confirm its impact explicitly in the task checklist.
+- If docs and code diverge, synchronize the affected documents and executable authorities in the same Feature task.
+- Record design-system exceptions and their removal conditions in `decisions.md`.
+- Store visual-reference files under a repository path such as `docs/designs/assets/<feature-name>/`; never depend on an absolute path from one person's computer.
+- Keep the external Figma or source URL for provenance, and also reference a repository asset when implementation depends on a fixed snapshot.
+
+## Backward Compatibility
+
+- `design-system.md`, visual briefs, and `Design Refs` are all optional.
+- Existing Feature docs do not need the new section backfilled.
+- This policy does not change spec/plan/tasks approvals or `workflow-stage` results.
+- For requests that do not match an explicit UI/UX activation condition, use the existing Feature-doc workflow only.

package/templates/en/common/designs/README.md

@@ -1,4 +1,4 @@
-# Designs
+# UX / Visual Designs
 
 Store design references used by the project.
 
@@ -6,19 +6,69 @@ Store design references used by the project.
 
 ---
 
+## Optional Use
+
+`design-system.md` and Feature visual briefs are not required documents for every project.
+
+- Consider them only for an explicit design-system, UI/visual-redesign, design-consistency, shared-UI/component-library, branding/theme/token, or Figma/design-image implementation request.
+- Do not create them for an ordinary web/frontend Feature, a backend Feature, or a bug fix that does not change durable design rules.
+- Detailed policy: `npx lee-spec-kit docs get ui-ux-design --json`
+
+---
+
 ## What belongs here
 
 - Screen/flow references (Figma, images, links)
 - Component/pattern guidelines (buttons, forms, navigation, etc.)
 - UI rules (brand, typography, colors/tokens)
 
+## Recommended Structure and Responsibilities
+
+```text
+docs/designs/
+├── README.md
+├── design-system.md
+├── <feature-visual-brief>.md
+└── assets/
+    └── <feature-name>/
+```
+
+- `design-system.md`: meaning and usage rules shared across Features
+- `<feature-visual-brief>.md`: Feature-specific Figma/images, UX direction, and gaps between the data contract and design
+- `assets/<feature-name>/`: repository-owned visual snapshots required by implementation
+
+If `design-system.md` already exists, reference or update it instead of creating a replacement. Do not make one `design.md` per Feature the default.
+
+---
+
+## What does not belong here
+
+- System/backend architecture (`docs/prd/*-overview.md` or the active Feature's `plan.md`)
+- Data models and API design (an Idea before promotion, then the active Feature's `plan.md`)
+- Open-source candidate research (an Idea or the active Feature's `decisions.md`)
+- Technical decisions and alternative comparisons (an Idea before promotion, then the active Feature's `decisions.md`)
+- Implementation roadmaps and work plans (the active Feature's `plan.md` and `tasks.md`)
+
+In `designs/`, design means UX, screen, and visual design—not technical design.
+
 ---
 
 ## Conventions
 
 - For external references, keep the **source URL + a short summary (or a snapshot)**.
 - Use kebab-case filenames (e.g., `auth-flow.md`, `design-system.md`).
-- If you need images/files, create and use an `assets/` folder.
+- Keep images/files in a repository path such as `assets/<feature-name>/`; never depend on an absolute path from one person's computer.
+- Use `scope: project` and the appropriate `kind: ux-design`, `kind: design-system`, or `kind: visual-reference` frontmatter.
+
+## Executable Authorities
+
+- `design-system.md`: meaning and usage rules
+- CSS theme/globals or token files: executed token values
+- Shared UI directory: executed component and variant contracts
+- Storybook or equivalent workbench: executable variant and state examples
+- Feature `decisions.md`: exceptions, change rationale, and removal conditions
+
+When `design-system.md` changes, use the same Feature task to review and synchronize affected docs, token/theme files, shared UI, Storybook/workbench examples, and verification.
 
 ---
 

package/templates/en/common/features/README.md

@@ -45,7 +45,7 @@ By the time work reaches this folder, the requirement should already be defined
 - Minimum **3-digit padding** for numbers (001, 002, ...)
 - Expands to **4+ digits** beyond 999 (F1000, F1001, ...)
 - Feature names in kebab-case
-- **Feature = Issue**: Each Feature corresponds to one GitHub Issue.
+- **Feature identity is workflow-dependent**: In GitHub workflow, each Feature corresponds to one GitHub Issue. In local workflow, the canonical identity is the stable Feature ID such as `F027`; no Issue is required.
 
 ---
 
@@ -57,6 +57,8 @@ npx lee-spec-kit workflow-stage <feature-ref> --json
 
 Use the returned `stage`, `nextAction`, and `implementationAllowed` values as the current workflow state.
 
+In a local workflow with `completionStrategy: "local-ff"` or `"local-squash"`, completion is `implementation_approve → local_merge → local_verify → local_cleanup → done`. Use the exact helper command returned for each stage. `local-ff` proves ancestry; `local-squash` proves the squash commit tree matches the internally preserved source Feature tip. Both require cleanup before `done`.
+
 ---
 
 ## PRD Requirement Traceability (Recommended)
@@ -129,9 +131,9 @@ Keeping the shared artifact for history is fine, but when it conflicts with feat
 
 ---
 
-## Pre-PR Fallback Checklist
+## Pre-PR Subagent Checklist
 
-Use `agents/skills/create-pr.md` (`Pre-PR Baseline Checklist`) as the default baseline for every Pre-PR review. Use review skills additionally for deeper inspection.
+Delegate every Pre-PR review to a fresh, read-only subagent using the model and reasoning effort returned by `workflow-stage --json`. The subagent follows `agents/skills/create-pr.md` (`Pre-PR Baseline Checklist`); the main agent owns finding remediation and evidence recording.
 
 ---
 

package/templates/en/common/features/feature-base/decisions.md

@@ -6,7 +6,8 @@ If unmanaged docs artifacts exist outside the canonical docs surface (for exampl
 > ADR (Architecture Decision Record) captures important technical or architectural choices made during implementation.
 > Write ADRs so the team can trace why a choice was made and revisit trade-offs later.
 
-> Format: `D{number}: {Decision Title} ({YYYY-MM-DD})`
+> Format: `DNNN: {Decision Title} ({YYYY-MM-DD})`
+> Decision IDs are scoped to this Feature and start at `D001`, independently of the Feature ID.
 
 Recording principles:
 
@@ -17,6 +18,7 @@ Recording principles:
   - Right before task done (`[DOING] -> [DONE]`): finalize `Options/Decision/Rationale` and enrich `Trace`
   - After PR merge: append 1-2 lines in `Trace (post-merge check)` with actual outcome/impact
 - Every ADR must include at least one **Evidence link** (commit, PR, or test/log evidence).
+- For a design-system change or exception, also record the affected rule and scope, rationale, removal condition, and synchronization impact on executable authorities.
 
 ---
 

package/templates/en/common/features/feature-base/spec.md

@@ -60,3 +60,6 @@
   - If this is a legacy requirements doc without PRD IDs yet, backfill IDs in the source first, then update this field and the `tasks.md` task tags together.
   - When requirements/scope change, update PRD docs + this field + `tasks.md` task tags together.
   - If implementation discovers a better user-facing behavior and the shipped requirement changes, treat that as a PRD update, not a permanent `[NON-PRD]` exception.
+- Design Refs: - (optional; use project-root paths only for explicit UI/UX design work)
+  - Design System: - (e.g. `docs/designs/design-system.md`)
+  - Visual Brief: - (e.g. `docs/designs/<feature-visual-brief>.md`)

package/templates/en/common/features/feature-base/tasks.md

@@ -13,6 +13,7 @@
   - Do not invent PRD IDs in `tasks.md`. Only reference IDs that already exist in `docs/prd` or the upstream requirements doc.
   - If this is a legacy feature without PRD IDs yet, backfill IDs in the source requirements doc first, then align `spec.md` `PRD Refs` and task tags together.
   - `[NON-PRD]` is for internal implementation work only. If the task changes user-facing behavior, acceptance criteria, or scope, backfill PRD first and tag it as `[PRD-...]`.
+- **Design-system synchronization (conditional)**: when a task changes `docs/designs/design-system.md`, track the affected design docs, token/theme files, shared UI, Storybook/workbench examples, and verification in that same task's `Checklist`. Do not edit an unaffected surface; confirm its impact instead.
 
 ---
 

package/templates/en/common/ideas/idea.md

@@ -30,6 +30,36 @@
 
 ---
 
+## Research and Candidate Comparison
+
+- Candidates:
+- Advantages:
+- Disadvantages:
+- License:
+- Validation Needed:
+
+---
+
+## Design Draft
+
+- Data Contracts:
+- Expected Components:
+- External Dependencies:
+- Open Questions:
+
+---
+
+## Feature Promotion Mapping
+
+- Content for `spec.md`:
+- Content for `plan.md`:
+- Content for `decisions.md`:
+- Content for `tasks.md`:
+
+> This is a pre-promotion draft. After Feature creation, move unresolved material as Candidate or Pending and keep the Idea for history only.
+
+---
+
 ## Promotion Notes
 
 - What should stay true if this becomes a feature?