architext 0.0.3 → 0.0.5

package/dist/templates/en/docs/prompts/start.md

@@ -1,7 +1,7 @@
 <protocol_kickoff>
   **Trigger**: `/archi.start [file_path]`
   **Phase**: Strategic Initialization
-  **Goal**: Establish Project Constitution (Vision/Tech/Roadmap) from Project Brief.
+  **Goal**: Establish project constitution (Vision/Tech/Roadmap) from Project Brief.
 
 <meta>
     <style>Strict, Professional, CLI-Like</style>
@@ -20,42 +20,37 @@
     **Action**:
     1. Parse `[file_path]` from trigger:
        - If path provided → read that file
-       - If not → search `project-brief.md` (project root), then `[[__DOCS_DIR__]]/project-brief.md`
+       - If not provided → search `project-brief.md` (project root), then `[[__DOCS_DIR__]]/project-brief.md`
        - If neither exists or empty → goto `<fallback_interview>`
 
-    2. **Resource Accessibility Check** (must complete before parsing):
-       Scan Brief for all external references (URLs, file paths, images). Try to access each; classify:
+    2. **Resource scan and read** (must complete before parsing):
+
+       **a) `brief-assets/` directory scan**: Check if `brief-assets/` exists at project root. If so, read all files (images/PDFs/docs/Schema). Match files referenced in Brief via `./brief-assets/filename` with files read here.
+
+       **b) Brief full-text external reference check**: Scan Brief for all external references (URLs, file paths, images). Try to access each:
 
        | Status | Handling |
        |:---|:---|
-       | Accessible | Read content, include in analysis |
+       | Accessible (incl. local files in brief-assets/) | Read content, include in analysis |
        | Inaccessible (auth required/404/private) | Mark `[unreadable]`, report to user later |
-       | Non-link references (e.g. "reference Linear's interaction") | Process normally, no fetch |
+       | Non-link descriptive references | Process normally, no fetch |
 
-       > Purpose: Avoid AI pretending it read resources it cannot access, leading to mismatched output.
+       **c) Asset semantic tag extraction**: For assets referenced in Brief as `- [semantic label] path`, record tag-to-file mapping for later steps (e.g. `[competitor reference]` → affects design_tokens, `[database Schema]` → affects data_snapshot).
 
-    3. Parse Brief sections, extract:
-       - Project feature tags (UI/Data/CLI/Lib/API — inferred from tech fields and paragraphs)
-       - Core feature list
-       - Pre-defined design decisions (user's preset design for specific features/pages/flows)
-       - Tech preferences (distinguish "confirmed" vs "blank/recommend")
-       - Existing resources and context
-       - Boundaries and constraints
-       - Reference projects
-       - Supplementary notes (rules/terminology/background)
+    3. Parse Brief sections, extract: project feature tags, core task list, business process (if any), pre-defined design decisions, tech preferences (distinguish "confirmed" vs "blank/recommend"), data model draft (if any), existing API endpoints (if any), existing resources, boundaries and constraints, reference projects, supplementary notes.
 
-    > Brief is a one-time input file; user may delete after processing.
+    > Brief is a one-time input file; user may delete after processing (brief-assets/ likewise).
 
     **Output**:
-    - If any resources inaccessible → **Immediately output Resource Accessibility Report** to user, list unreadable links, ask for alternatives (screenshot, paste content, text description). Wait for user reply before continuing.
-    - If all accessible or no external refs → Internal summary (no user output), proceed to `<step_1_gap_analysis>`.
+    - If any resources inaccessible → **Immediately output Resource Accessibility Report**, wait for user reply before continuing.
+    - If all accessible or no external refs → Internal summary, proceed to `<step_1_gap_analysis>`.
 </step_0_ingest>
 
 <step_1_gap_analysis>
-    **Role**: Chief Product Officer (CPO)
+    **Role**: Chief Product Strategist (CPO)
     **Input**: Step 0 parsing result.
 
-    **Action**: Check Brief completeness, identify information gaps.
+    **Action**: Check Brief completeness item by item, identify information gaps.
 
     **Checklist**:
 
@@ -63,196 +58,155 @@
     |:---|:---|:---|
     | Project identity | Name + one-line description + problem statement all filled | Required |
     | Target users | At least core user role described | Required |
-    | Core features | At least 2 concrete features, each with description | Required |
+    | Core tasks | At least 2 concrete tasks listed, each with description | Required |
     | Tech stack – core | Language/runtime + core framework filled (non-empty) | Required |
     | Tech stack – optional | DB/ORM/CSS/deploy etc. blanks | Can supplement |
-    | Project starting point | New project or existing codebase (affects architecture) | Required |
+    | Project starting point | New or existing codebase (affects architecture) | Required |
     | Existing resources | Design/brand/existing API/3rd-party services explicit? | Can supplement |
-    | Style/tone | [?UI] Visual keywords / [?CLI] Output style / [?API] Doc approach | Can supplement |
+    | Style/tone | (UI projects only) Visual keywords / (CLI projects only) Output style / (API projects only) Doc approach | Can supplement |
     | Boundaries | At least 1 anti-goal or hard constraint declared | Suggested |
     | Success metrics | Concrete quantifiable metrics filled | Suggested |
     | Reference projects | At least 1 reference listed | Suggested |
 
-    **Gap levels**:
-    - **Required**: Must ask in Step 2
-    - **Can supplement**: AI can recommend but better to confirm
-    - **Suggested**: AI can infer, does not block flow
-
-    **Decision**:
-    - No "Required" gaps + no "Can supplement" gaps → skip Step 2, go to Step 3
-    - Otherwise → go to Step 2
-
-    **Output**: Brief analysis summary:
-    ```
-    ### BRIEF Analysis Report
-    > **Project**: [name] | **Features**: [activated UI/Data/CLI/Lib/API tags]
+    **Gap levels**: Required → must ask in Step 2 | Can supplement → AI can recommend, suggest confirm | Suggested → AI can infer
 
-    **Confirmed**:
-    - [list of filled items]
+    **Decision**: No "Required" + "Can supplement" gaps → skip Step 2 | Has gaps → proceed to Step 2
 
-    **Gaps (require supplement)**:
-    - [gap 1]
-    - [gap 2]
-
-    **AI will auto-complete** (no action):
-    - [items AI can infer]
-    ```
+    **Output**: Output BRIEF analysis report to user — include project name/feature tags, confirmed items list, information gap list (require supplement), AI auto-complete items.
 </step_1_gap_analysis>
 
 <step_2_supplementary>
-    **Role**: Product Advisor
     **Trigger**: Only when Step 1 finds "Required" or "Can supplement" gaps.
     **Input**: Step 1 gap list. Max 3–6 questions.
 
-    [[SKILL: Follow `archi-interview-protocol` Skill's core rules and standard output format.]][[NO-SKILL: (Skill not installed: read `[[__DOCS_DIR__]]/skills/archi-interview-protocol/SKILL.md` and follow its rules)]]
+    [[SKILL: archi-interview-protocol|Follow the skill's core rules and standard output format for questioning.]][[NO-SKILL: (Skill not installed: read `[[__DOCS_DIR__]]/skills/archi-interview-protocol/SKILL.md` and follow its rules)]]
 </step_2_supplementary>
 
 <step_3_constitution>
     **Role**: Chief Architect
-    **Input**: Full Brief text + Step 2 answers (if any).
+    **Input**: Full Brief + Step 2 supplement answers (if any).
 
     **Action**: Generate project constitution files in one pass. All Brief content must be consumed and routed; nothing omitted.
 
     ### Information Routing Rules
 
-    > Rule files (`02_tech_stack`, `90_custom_rules`, etc.) are already injected into context by the IDE — the AI knows their paths; write directly.
+    > Rule files (`02_tech_stack`, `90_custom_rules`, etc.) are already injected into context by IDE; AI knows their paths, write directly.
 
     | Brief content | Target file |
     |:---|:---|
     | Project identity, target users, success metrics, references | `[[__DOCS_DIR__]]/global/vision.md` |
     | Tech stack, deploy target, 3rd-party libs/services | rule file `02_tech_stack` |
-    | Style/tone (UI/CLI/API) — aesthetic direction / density / motion | rule file `02_tech_stack` (UI Protocol) + `design_tokens.json` aestheticDirection + motion.preference + illustration |
-    | [?UI] **Aesthetic direction** (saas-dark/saas-light/dashboard/marketing/mobile-app/editorial/brutalist/custom) | `design_tokens.json` `aestheticDirection.preset` + `aestheticDirection.customDescription` |
-    | [?UI] **Visual Reference** (brand palette / font / icon library / competitor screenshots / forbidden styles) | `design_tokens.json` primitivePalette.brand + illustration + motion; screenshots/URLs → `vision.md` Visual Reference |
-    | Core feature list | `[[__DOCS_DIR__]]/global/roadmap.json` |
-    | **Pre-defined design decisions** | Inject into related tasks' `goal` in Roadmap; treat as hard constraint in `/archi.plan` |
-    | Boundaries and anti-goals | `[[__DOCS_DIR__]]/global/vision.md` Boundaries |
-    | Existing resources (design/brand/existing API) | `[[__DOCS_DIR__]]/global/vision.md` + rule file `02_tech_stack` by content |
-    | **Rules/conventions/preferences** from supplementary notes | rule file `90_custom_rules` |
-    | **Domain terminology** from supplementary notes | `[[__DOCS_DIR__]]/global/dictionary.json` |
-    | **Other background info** from supplementary notes | `[[__DOCS_DIR__]]/global/vision.md` Context |
-
-    > Key: Any rule-like content (e.g. "comments in English", "no any") in supplementary notes must go to rule file `90_custom_rules`, not discarded.
+    | Style/tone — aesthetic direction / density / motion preference | `02_tech_stack` (UI Protocol) + `design_tokens.json` |
+    | (UI projects only) Aesthetic preset + visual reference (brand palette / font / icon / competitor screenshots) | `design_tokens.json` corresponding fields + `vision.md` Visual Reference |
+    | (UI projects only) Images in brief-assets/ tagged `[competitor reference]` | `design_tokens.json` aestheticDirection reference + `vision.md` Visual Reference |
+    | Core task list | `[[__DOCS_DIR__]]/global/roadmap.json` |
+    | Business process (if any) | Inject into Roadmap task `description` / `goal`; aids `/archi.plan` context |
+    | Pre-defined design decisions | Inject into Roadmap task `goal`; hard constraint in `/archi.plan` |
+    | (Data projects only) Data model draft (if any) | `data_snapshot.json` initial entity skeleton |
+    | (API projects only) Existing API endpoints (if any) | `vision.md` Context + Roadmap task `description` injection |
+    | Files in brief-assets/ tagged `[database Schema]` | Parse and write to `data_snapshot.json` |
+    | Files in brief-assets/ tagged `[API docs]` | Parse and route to `vision.md` Context + related Roadmap tasks |
+    | Boundaries and anti-goals | `vision.md` Boundaries |
+    | Existing resources | `vision.md` + `02_tech_stack` by content |
+    | Rules/conventions/preferences from supplementary notes | rule file `90_custom_rules` |
+    | Domain terminology from supplementary notes | `dictionary.json` |
+    | Other background from supplementary notes | `vision.md` Context |
+
+    > Key: Rule-like content in supplementary notes must go to `90_custom_rules`; do not discard.
 
     ### 3.1 Vision (`[[__DOCS_DIR__]]/global/vision.md`)
-    - Fill from Brief project overview: Core Vision, Target Audience
-    - Fill from Brief boundaries: Boundaries
-    - Fill from Brief style/tone (if any): Design & Experience
-    - Derive Product Principles from Brief references
-    - Extract background context from Brief existing resources + supplementary notes
-    - Fill all `[ ]` placeholders; do not retain template example text
+    - Fill from Brief: Core Vision / Target Audience / Boundaries / Design & Experience / Product Principles / background context
+    - Fill all placeholders; do not retain template example text
 
     ### 3.2 Tech Stack (rule file `02_tech_stack`)
-    - Confirmed tech in Brief → write directly
-    - Blank/"recommend" in Brief → AI recommends by project features; mark `(AI Recommended)` and brief rationale
-    - Brief 3rd-party services/API → write in corresponding Section
-    - **AX Optimization**: Prefer AI-friendly tech (Static Typing, Popular Frameworks, Convention-over-Configuration)
-    - Fill all Section 1-9 (Global Mandates, Technology Selection, Coding Standards, UI Protocol[?UI], Testing, Deployment, Architecture, Anti-Patterns, **Project Conventions**)
-    - Section 5 Testing: Environment Scripts must be complete
-    - **Section 9 Project Conventions**: Establish global architecture conventions based on Brief and project features. `/archi.plan` will auto-inherit these instead of re-asking per feature:
-      - **Error Handling**: Infer from project type — [?UI] Fail Fast + Form Validation; [?CLI] Fail Fast (stderr); [?API] Schema Validation + Fail Fast; space-separated for multi-select
-      - [?UI] **Data Flow**: Based on realtime needs — no realtime → Standard Request (+ SWR/React Query if applicable); Brief mentions realtime/collab → Realtime
-      - [?Web/API] **Auth & Access**: Based on Brief user roles — single role → Authenticated; multi-role → RBAC; no auth mentioned → leave empty for per-feature decision in Plan
-      - Each item must have Strategy/Default + Rationale (rationale must be specific to this project)
+    - Brief confirmed → write directly | Blank/"recommend" → AI recommends and mark `(AI Recommended)` + rationale
+    - **AX Optimization**: Prefer AI-friendly tech when recommending
+    - Fill complete Section 1-9
+    - **Section 9 Project Conventions**: Establish global conventions by project features (Error Handling / Data Flow / Auth & Access); `/archi.plan` will auto-inherit
+      - Error Handling: (UI projects only) Fail Fast + Form Validation / (CLI projects only) Fail Fast (stderr) / (API projects only) Schema Validation + Fail Fast
+      - (UI projects only) Data Flow: No realtime need → Standard Request / Brief mentions realtime → Realtime
+      - (UI or API projects only) Auth & Access: Single role → Authenticated / Multi-role → RBAC / No description → leave empty for Plan
+      - Each item must have Strategy/Default + Rationale
 
     ### 3.3 Custom Rules (rule file `90_custom_rules`)
-    - Extract rule-like content from Brief supplementary notes
-    - Convert Brief tech red lines into concrete prohibitions
-    - If user provided nothing, keep template default
+    - Extract rule-like content from Brief supplementary notes + convert tech red lines to prohibitions
 
     ### 3.4 Roadmap (`[[__DOCS_DIR__]]/global/roadmap.json`)
-    [[SKILL: Follow the `archi-decompose-roadmap` Skill protocol to generate the task chain from the Brief feature list and write to roadmap.json]][[NO-SKILL: (Skill not installed: read `[[__DOCS_DIR__]]/skills/archi-decompose-roadmap/SKILL.md` and follow its protocol)]], then proceed to the next step immediately without user confirmation.
+    [[SKILL: archi-decompose-roadmap|Follow the skill protocol to generate task chain from Brief task list, write to roadmap.json; proceed to next step immediately without user confirmation.]][[NO-SKILL: (Skill not installed: read `[[__DOCS_DIR__]]/skills/archi-decompose-roadmap/SKILL.md` and follow its protocol)]]
 
     ### 3.5 Other global docs (as needed)
     - `dictionary.json`: Extract domain terms from Brief
-    - [?Data] `data_snapshot.json`: Initialize core entity skeleton (entity names + primary key fields) from Brief data descriptions; write empty template if no data descriptions provided
-    - [?UI] `design_tokens.json`: Populate from Brief "Style & Tone" and "Visual Reference":
-      - `aestheticDirection.preset`: From Brief aesthetic direction field; if blank, infer from project features (Web SaaS → saas-light, Dashboard → dashboard, etc.)
-      - `aestheticDirection.customDescription`: Only fill when preset is "custom"
-      - `primitivePalette.brand`: Extract Hex values from brand palette; leave empty if none
-      - `mode`: Infer default + support array from aesthetic direction (saas-dark → default:"dark", saas-light → default:"light", etc.)
-      - `motion.preference` / `motion.patterns`: Set from motion preference (subtle / rich / none); expand patterns for rich
-      - `illustration.style` / `illustration.iconLibrary`: Set from illustration style and icon library fields
-      - `semanticTokens.colors`: If brand color present, fill Primary using Brand-600/Brand-500 keys
-    - `error_codes.json`: Predefine core error codes from feature list
+    - (Data projects only) `data_snapshot.json`: Initialize core entity skeleton; write empty template if no data description
+    - (UI projects only) `design_tokens.json`: Fill aestheticDirection / primitivePalette / mode / motion / illustration / semanticTokens from "Style & Tone" and "Visual Reference"
+    - `error_codes.json`: Predefine core error codes from task list
 
     ### 3.6 Map (`[[__DOCS_DIR__]]/global/map.json`)
-    - `directoryMapping`: Pre-register core directory skeleton based on architecture pattern declared in tech_stack
-      (e.g. `src/commands/`, `src/core/`, `src/utils/`); each directory with a one-line purpose description
-    - `logicalTopology`: Empty array for now; populate during `/archi.plan`
-    - `criticalUserJourneys`: Empty array
-    - `featureRelations`: Empty array
-
-    **Output**: Write all files, then run `npx archi render` to generate visual `.md`.
-</step_3_constitution>
+    - `directoryMapping`: Pre-register core directory skeleton from tech_stack architecture pattern
+    - `logicalTopology` / `criticalUserJourneys` / `featureRelations`: Empty array for now
 
-<step_4_audit>
-    **Role**: Chief Auditor
-    **Checklist**:
-    1.  **Vision completeness**: Does `vision.md` include North Star metric and design philosophy?
-    2.  **Tech Stack consistency**: Is rule file `02_tech_stack` aligned with Brief preferences? Contains full stack?
-    3.  **Custom Rules**: Did Brief supplementary notes/tech red lines get written to rule file `90_custom_rules`?
-    4.  **Roadmap compliance**: Run `npx archi task --check` to verify.
-    5.  [?UI] **Design Tokens**: Does `design_tokens.json` have base color/font/spacing definitions?
-    6.  **Brief alignment**: All Brief core features mapped to Roadmap tasks?
-    7.  **Zero omission**: All user-provided content routed to correct files?
-
-    Silently fix issues; mark critical ones with `Risk Warning`.
-</step_4_audit>
-
-<step_4_5_ui_wireframe>
-    **Trigger**: Only when project features include [?UI].
-    **Action**: Auto-invoke `archi-ui-wireframe` Skill (Phase 1 wireframe).
+    UI projects only: **UI concept design**: [[SKILL: archi-ui-wireframe|Follow the skill protocol to auto-generate UI concept design.]][[NO-SKILL: (Skill not installed: read `[[__DOCS_DIR__]]/skills/archi-ui-wireframe/SKILL.md` and follow its protocol)]]
     - Start generation without user confirmation
     - Read the just-written vision.md + roadmap.json + design_tokens.json + 02_tech_stack
     - Write `ui_concept.html` + `ui_context.md`
-    - Output Phase 1 wireframe summary; await user confirmation before entering Phase 2 styling
+    - Output UI concept design summary; await user confirmation or feedback for adjustments
 
-    > This step promotes UI wireframe generation from "recommended next step" to "auto-completed by start", reducing manual user actions.
-</step_4_5_ui_wireframe>
+    **Output**: Write all files, then run `npx archi render`. Enter step_4_verify.
+</step_3_constitution>
 
-<step_5_signoff>
-    **Terminal Gate** (Do not skip; must complete before output summary):
-    | Step | Command | Pass Condition |
-    |:---|:---|:---|
-    | 1 | `npx archi task --check` | No ERROR-level issues |
-    | 2 | `npx archi render` | `.md` views generated |
+<step_4_verify>
+    **Role**: Independent Reviewer
+    [[SUBAGENT: archi-silent-audit|mode: init, context: Review step_3 generated global files (vision, tech_stack, roadmap, dictionary, etc.)]][[NO-SKILL: (Skill not installed: read `[[__DOCS_DIR__]]/skills/archi-silent-audit/SKILL.md`, follow mode: init review dimension table item by item)]]
+
+    [[INCLUDE: shared/verify-result-handling.md]]
+</step_4_verify>
 
-    **Action** (After Gate passes):
-    1.  Run `npx archi task` to output task progress.
+<step_5_signoff>
+    **Terminal Gate** (do not skip): Standard check (task --check + render).
+
+    **Pre-signoff Checklist** (confirm each item after Gate passes, before Output):
+    □ vision.md — all placeholders replaced, no template example text remaining
+    □ 02_tech_stack.md — Sections 1-9 fully filled, Section 9 Project Conventions includes Strategy + Rationale
+    □ roadmap.json — archi-decompose-roadmap Skill executed, task chain generated
+    □ map.json — core directory skeleton pre-registered (directoryMapping)
+    □ dictionary.json + error_codes.json — domain terms and core error codes extracted
+    □ (UI projects only) design_tokens.json + ui_concept.html + ui_context.md — generated
+    □ (Data projects only) data_snapshot.json — initial entity skeleton written
+    □ Step 4 Silent Audit — executed, all CRITICAL issues resolved
+
+    **Action** (after Checklist confirmed):
+    1.  Run `npx archi task` to output task progress overview.
     2.  Output summary.
 
-    **Output**: Project init summary including:
-    - **Brief adoption**: Key decisions adopted from Brief
+    **Output**: Project init summary, including:
+    - **Brief source confirmation**: Key decisions adopted from Brief
     - **AI completions**: Tech/decisions AI recommended and rationale
     - **Roadmap overview**: Task count and phase distribution
     - **Next Steps table**:
 
     | Priority | Action | Notes |
     |:---|:---|:---|
-    | [?UI] Recommended | Reply **OK** to enter Phase 2 styling | Phase 1 wireframe auto-generated; confirm layout then style |
+    | (UI projects only) Recommended | Review ui_concept.html | UI concept design auto-generated; confirm layout and visuals in browser |
     | Recommended | `/archi.plan INF-01` | Plan the first infrastructure task |
-    | Optional | `/archi.scope <scope-brief.md>` | Append more requirements to Roadmap if needed |
+    | Optional | `/archi.scope <scope-brief.md>` | If more requirements to decompose, append to Roadmap |
 </step_5_signoff>
 
 <fallback_interview>
     **Trigger**: Brief file not found or empty.
-    **Role**: Product Advisor
 
     **Action**:
-    1. Tell user `project-brief.md` not found. Suggest:
+    1. Inform user `project-brief.md` not found. Suggest:
        - Check project root for the file (should have been generated by `npx archi init`)
        - If lost, re-run `npx archi init` to regenerate
        - Or continue conversation and provide info via interview
-    2. If user continues via conversation, guide in this order:
+    2. If user chooses to continue conversation, guide in this order:
        a. What is the project? (name, one-line description, problem solved)
        b. Who is it for? (target users)
-       c. Core features? (at least 2–3)
+       c. What are the core tasks? (at least 2–3)
        d. Tech stack? (language/framework, confirmed parts)
-       e. Constraints? (anti-goals, timeline, compatibility)
+       e. What constraints? (anti-goals, timeline, compatibility)
     3. After collection, write to `project-brief.md` (project root), then goto `<step_1_gap_analysis>`.
 
-    > Fallback for backward compatibility; Brief remains the primary flow.
+    > This mode is for backward compatibility; core flow remains Brief-driven.
 </fallback_interview>
 
 </protocol_kickoff>

package/dist/templates/en/docs/shared/verify-result-handling.md

@@ -0,0 +1,6 @@
+**Review result handling**:
+| Level | Handling |
+|:---|:---|
+| CRITICAL | Must fix before continuing |
+| WARNING | Must explain handling in signoff |
+| INFO | May decide at discretion |

package/dist/templates/en/docs/templates/design.template.md

@@ -0,0 +1,77 @@
+---
+description: "[?Complex] Technical Design — Defines implementation strategy, state flow, parameters and invariants for core mechanisms. Generated only when the task involves non-trivial technical decisions."
+glue: Bridges spec.md (WHAT) and plan.json (DO), defining HOW. plan.json tasks must cover all mechanisms in this doc; spec.md § 2 AC must be traceable to complete paths in this design.
+---
+
+# Technical Design: {FEATURE_NAME}
+
+> **Spec**: `spec.md` (Acceptance Criteria — constraint source for this design)
+> **Plan**: `plan.json` (Execution tasks — downstream consumer of this design)
+> **Trigger**: [AI: One sentence explaining why this task needs technical design]
+
+## 1. Solution Overview
+
+<!-- [AI]: 2-3 sentences summarizing the technical approach and key trade-offs.
+  - Reference plan.json decisions (e.g. "Data Flow=Realtime WebSocket")
+  - Explain why this approach over alternatives (brief ref if discussed in step_2)
+  - Do not repeat spec.md acceptance criteria; this section answers "how to implement" not "what to implement"
+-->
+
+## 2. Core Mechanisms
+
+<!-- [AI]: Main body of this doc. Select ≥1 structured pattern per technical need.
+  Each mechanism in its own subsection (2.1, 2.2, ...), labeled with pattern type.
+  Same task may combine patterns (e.g. State Machine for connection mgmt + Pipeline for message handling).
+
+  [[SKILL: archi-design-patterns|Follow the skill's pattern selection guide, generate standard-format tables and run self-checks. If any check fails, fix and re-check before proceeding to next mechanism.]]
+-->
+
+### 2.1 [Mechanism Name] — Pattern: [State Machine / Pipeline / Decision Matrix / Protocol]
+
+<!-- Fill per archi-design-patterns skill's standard format for the chosen pattern -->
+
+## 3. Parameters
+
+<!-- [AI]: All concrete numeric values used across mechanisms, centralized.
+  Prohibit vague descriptions (e.g. "appropriate timeout", "reasonable interval"); must state concrete value + unit + rationale.
+
+  | Parameter | Value | Unit | Rationale |
+  |:---|:---|:---|:---|
+  | [name] | [value] | [unit] | [why this value] |
+-->
+
+## 4. Invariants
+
+<!-- [AI]: Assertions that must hold at any time. Each must be assertable or testable.
+  Format: [INV-N] assertion description
+
+  Constraints:
+  - Each invariant must map to at least one plan.json test entry or task notes verification
+  - Invariants are implementation "guardrails": AI must ensure no violation when writing code
+-->
+
+## 5. Failure Modes
+
+<!-- [AI]: Explicitly list possible failure scenarios for core mechanisms. Each must have detection and response.
+
+  | Failure | Detection | Response | Fallback |
+  |:---|:---|:---|:---|
+  | [description] | [how to detect: event/timeout/exception type] | [primary recovery: retry/reconnect/rollback] | [if recovery fails: switch mode/prompt user/silent log] |
+
+  Constraints:
+  - Detection must be concrete (no "on error"; write "4xx response / 3 heartbeat timeouts / catch TypeError")
+  - Fallback must be observable (no "report error"; write specific UI feedback or exit code)
+-->
+
+## 6. Trace Verification
+
+<!-- [AI]: From each spec.md § 2 AC, trace the execution path through this design.
+
+  | AC (from spec § 2) | Trace Path (execution chain in this design) | Result |
+  |:---|:---|:---|
+  | [Given X When Y Then Z] | [State A →(event)→ State B →(action)→ State C] or [Pipeline Step 1→2→3] | ✓ Reachable |
+  | [Given X When Error Then W] | [State A →(error)→ State D; Failure Mode #2 → fallback] | ✓ Reachable |
+
+  **Gap Check**: If an AC cannot be traced → design has a gap; return to § 2 to add mechanism or § 5 to add failure handling.
+  Design is deliverable only when all ACs are ✓.
+-->

package/dist/templates/en/docs/templates/spec.template.md

@@ -1,51 +1,86 @@
 ---
-description: Behavioral Specification (Gherkin) for {FEATURE_NAME}.
+description: Task Specification for {FEATURE_NAME}.
 ---
 
 # Task Spec: {FEATURE_NAME}
 
 > **Status:** [Draft]
-> **Context:** [AI: Insert a 1-sentence summary of the task's value]
+> **Task Type:** [Feature / Infra / Polish]
+> **Context:** [AI: One-sentence summary of this task's goal and value]
 
-## 1. User Stories
+## 1. Overview
 
-<!-- [AI Instruction]: Brief user value, describe task requirements from user perspective -->
+<!-- [AI]: Brief task background, goal, and user value (2-3 sentences).
+  - FEAT task: From user perspective describe "As a [Role], I want to [Action], So that [Benefit]"
+  - INF task: Describe the downstream scope this infrastructure supports
+  - POLISH task: Describe current state and optimization target
+-->
 
-- **As a** [Role] (e.g. Registered User), **I want to** [Action] (e.g. Post a comment), **So that** [Benefit] (e.g. Interact with other users).
+## 2. Acceptance Criteria
 
-## 2. Behavioral Specifications (Gherkin)
+<!-- [AI]: Core acceptance contract — sole basis for development and testing.
+  Select applicable dimension format by Task Type (inferred from ID prefix); may combine multiple dimensions.
 
-<!-- [AI Instruction]: Core logic contract. The sole basis for development and testing. -->
+  === Dimension Building Blocks (select at least one primary dimension) ===
 
-### Scenario: [Happy Path Name, e.g. User submits successfully]
+  ▸ Behavioral [FEAT primary]
+    Use Gherkin Given/When/Then to define system behavior paths (happy + exception).
 
-- **Given** User is in [Pre-state] (e.g. Logged in and form is valid)
+  ▸ Structural [INF primary]
+    Use Configuration Contract to define target state of files/config:
+    - Path: file path
+    - Key Settings: key config items and concrete values (no generic descriptions like "configure X")
+    - Constraints: technical red lines
+    - Verify: executable command + expected output
 
-- **When** User performs [Action] (e.g. Clicks submit button)
+  ▸ Quantitative [POLISH primary]
+    Use Quality Target to define measurable goals:
+    - Metric: metric name
+    - Baseline: current value
+    - Target: target value
+    - Verify: measurement method
 
-- **Then** System should return [Expected Result] (e.g. Show success Toast)
+  ▸ Contractual [integration / shared engine]
+    Define interface contracts for external exposure or integration:
+    - External API Input/Output/Error mapping
+    - Shared module export type signatures
 
-- **And** Database record should [State Change] (Ref: `data_snapshot.json`)
+  ▸ Invariant [refactoring]
+    Declare behavior/interface that must remain unchanged:
+    - Preserve: [behavior or interface that must not change]
+    - Verify: [regression verification method]
 
-### Scenario: [Edge Case Name, e.g. Network timeout]
+  === Mixed task example ===
+  INF task may include Behavioral sub-dimension (e.g. hotkey registration has behavior path)
+  FEAT task may include Structural sub-dimension (e.g. config file creation)
+  Use sub-headings to distinguish dimensions.
+-->
 
-- **Given** User network is unstable
+## 3. Data Requirements
 
-- **When** User clicks submit button
+<!-- [AI]: [?Data] Declare data changes, reference table structure in data_snapshot.json.
+  Write "N/A" when no data changes.
 
-- **Then** System should show [Error Message] (Ref: `error_codes.json`)
+  * Schema: [Table Name] -> [Field] (Add/Modify)
+  * API: [Method] [Path]
+  * Permissions: [Required Role]
+-->
 
-- **And** Should not produce dirty data
+## 4. Interface Exports
 
-## 3. Data Requirements
+<!-- [AI]: [?Upstream] Public interfaces, conventions, import paths this task exposes to downstream tasks.
+  Downstream tasks depend on this declaration rather than guessing. Omit when no downstream consumers.
 
-<!-- [AI Instruction]: Explicit data changes, must reference table structure in `data_snapshot.json` -->
+  Format:
+  | Export | Value | Consumer |
+  |:---|:---|:---|
+  | [convention/API/path alias/script] | [concrete value] | [downstream task ID] |
+-->
 
-* **Schema**: [Table Name] -> [Field] (Add/Modify)
-  - Example: `Comment` -> `content` (Add), `parent_id` (Add, nullable)
+## 5. Constraints
 
-* **API**: [Method] [Path]
-  - Example: `POST /api/comments`, `GET /api/comments/:id`
+<!-- [AI]: Extract red-line constraints relevant to this task from vision.md + 02_tech_stack.md.
 
-* **Permissions**: [Required Role]
-  - Example: `authenticated` (for POST), `public` (for GET)
+  Format:
+  - [constraint content] (ref: [source])
+-->