architext 0.0.4 → 0.0.6

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,190 +58,161 @@
     |:---|:---|:---|
     | 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
+    **Gap levels**: Required → must ask in Step 2 | Can supplement → AI can recommend, suggest confirm | Suggested → AI can infer
 
-    **Output**: Brief analysis summary:
-    ```
-    ### BRIEF Analysis Report
-    > **Project**: [name] | **Features**: [activated UI/Data/CLI/Lib/API tags]
+    **Decision**: No "Required" + "Can supplement" gaps → skip Step 2 | Has gaps → proceed to Step 2
 
-    **Confirmed**:
-    - [list of filled items]
-
-    **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: archi-interview-protocol|Follow the 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 (`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.
+    | Tech stack, deploy target, 3rd-party libs/services | rule file `tech_stack` |
+    | Style/tone — aesthetic direction / density / motion preference | `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` + `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
-
-    ### 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)
+    - 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 `tech_stack`)
+    - 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: archi-decompose-roadmap|Follow the skill protocol to generate the task chain from the Brief feature list and write to roadmap.json, then proceed to the next step immediately without user confirmation.]][[NO-SKILL: (Skill not installed: read `[[__DOCS_DIR__]]/skills/archi-decompose-roadmap/SKILL.md` and follow its protocol)]]
+    [[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
+    - (API projects only) `api_snapshot.json`: Initial endpoint registration; extract from Brief if API description exists, otherwise write empty template
+    - `env_registry.json`: Initial env var registration
+    - (CLI projects only) `command_api.json`: Initial command registration; extract from Brief if command description exists, otherwise write empty template
+    - (Lib projects only) `public_api.json`: Initial export registration; extract from Brief if export description exists, otherwise write empty template
+
+    UI projects only: **UI concept design**: Skip — completed independently by `/archi.ui`. Only ensure `design_tokens.json` is populated.
 
     ### 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
+    - `directoryMapping`: Pre-register core directory skeleton from tech_stack architecture pattern
+    - `logicalTopology` / `criticalUserJourneys` / `featureRelations`: Empty array for now
 
-    **Output**: Write all files, then run `npx archi render` to generate visual `.md`.
+    UI projects only: **UI concept design**: Skip — completed independently by `/archi.ui`.
+
+    **Output**: Write all files, then run `npx archi render`. Enter step_4_verify.
 </step_3_constitution>
 
 <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>
 
-<step_4_5_ui_wireframe>
-    **Trigger**: Only when project features include [?UI].
-    **Action**: [[SKILL: archi-ui-wireframe|Follow the skill protocol to auto-invoke Phase 1 wireframe generation.]][[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
-
-    > This step promotes UI wireframe generation from "recommended next step" to "auto-completed by start", reducing manual user actions.
-</step_4_5_ui_wireframe>
-
 <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 |
-
-    **Action** (After Gate passes):
-    1.  Run `npx archi task` to output task progress.
+    **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
+    □ 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 + env_registry.json — domain terms, core error codes, env vars extracted
+    □ (UI projects only) design_tokens.json — generated
+    □ (Data projects only) data_snapshot.json — initial entity skeleton written
+    □ (API projects only) api_snapshot.json — initial API endpoints registered
+    □ (CLI projects only) command_api.json — initial CLI commands registered
+    □ (Lib projects only) public_api.json — initial lib exports registered
+    □ 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 | `/archi.ui` | Generate UI concept design (`screens/` multi-file structure) |
     | Recommended | `/archi.plan INF-01` | Plan the first infrastructure task |
-    | Optional | `/archi.scope <scope-brief.md>` | Append more requirements to Roadmap if needed |
+    | (Post-INF) | `/archi.script` | Generate AI automation scripts (validate/dev-up/dev-reset) |
+    | 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/prompts/ui.md

@@ -0,0 +1,113 @@
+<protocol_ui>
+  **Trigger**: `/archi.ui` | Auto-loaded by Workflow Dispatch on natural language trigger
+  **Goal**: Generate or incrementally update multi-file UI concept designs (`screens/` directory).
+
+<meta>
+    <style>Visual, Systematic, Incremental</style>
+    <language>English</language>
+    <principles>
+      1.  **Auto-Detect**: No subcommands; automatically detects `screens/` directory state to decide full generation or incremental update.
+      2.  **Multi-File**: Each screen as independent `S-XX.html`, shared styles in `_shared.css`, `index.html` as navigation hub.
+      3.  **Token-Driven**: Visual styles strictly from `design_tokens.json`; no hardcoding.
+      4.  **IDE-Native First**: Leverage IDE native capabilities to drive execution rhythm; this protocol defines quality standards and checkpoints without fighting IDE planning/execution mechanisms.
+    </principles>
+</meta>
+
+<step_1_load>
+    **Action**:
+    1.  **Pre-flight**: Check `architext.json` → `features` contains `ui`. If not → reject ("UI feature not enabled for this project").
+    2.  **Load**: vision.md (platform/users/north star), roadmap.json (UI-related tasks), design_tokens.json, tech_stack.md (platform/navigation framework), ui_context.md (if exists).
+    3.  **Mode Detection**:
+
+        | Condition | Mode | Behavior |
+        |:---|:---|:---|
+        | `screens/` directory does not exist | **Full Generation** | Extract all UI screens from roadmap → step_2 |
+        | `screens/` exists | **Incremental Update** | Compare roadmap + ui_context.md, identify new/changed screens → step_2 |
+
+    **Output**: Mode determination + context summary. Proceed to step_2_plan.
+</step_1_load>
+
+<step_2_plan>
+    **Action**:
+
+    **Full mode**: Extract all UI-related screens from roadmap tasks, assign screen IDs (S-01, S-02...).
+    **Incremental mode**: Compare existing `screens/` with roadmap, identify differences:
+
+    | Diff Type | Action |
+    |:---|:---|
+    | New screen (roadmap has task but no corresponding S-XX) | Assign new ID, add to generation list |
+    | Screen change (existing screen's task has requirement changes) | Add to update list |
+    | No change | Skip |
+
+    **Tokens Check**: Check `design_tokens.json`:
+    - `aestheticDirection.preset` empty → guide selection
+    - `primitivePalette.brand` empty → guide Hex input
+    - Other empty values → AI infers, non-blocking
+
+    **Output**: Screen plan list (ID / Name / Task / States / Action: add/update/skip).
+
+    **Gate**: User replies **OK** to proceed to step_3_generate; no file generation without confirmation.
+</step_2_plan>
+
+<step_2_5_refinement>
+    **Trigger**: User replies non-OK, with corrections, screen additions/removals, or mapping adjustments.
+    **Action**: Incorporate feedback, refresh screen plan list and re-output, await confirmation.
+
+    User replies OK → proceed to step_3_generate.
+</step_2_5_refinement>
+
+<step_3_generate>
+    **Action**: Call Skill for actual generation.
+
+    [[SKILL: archi-ui-wireframe|Follow skill protocol to generate multi-file UI concept designs based on confirmed screen plan. Full mode generates all screens; incremental mode generates only new/changed screens.]][[NO-SKILL: (Skill not installed: read `[[__DOCS_DIR__]]/skills/archi-ui-wireframe/SKILL.md` and follow its protocol)]]
+
+    **Artifacts**:
+    - `[[__DOCS_DIR__]]/global/screens/_shared.css` — CSS variables (from design_tokens) + base layout + control bar styles
+    - `[[__DOCS_DIR__]]/global/screens/S-XX.html` — Each screen as independent file
+    - `[[__DOCS_DIR__]]/global/screens/index.html` — Navigation hub listing all screens
+    - `[[__DOCS_DIR__]]/global/ui_context.md` — AI screen index (routes reference `screens/S-XX.html`)
+
+    **Output**: Generated file list + change summary. Proceed to step_4_verify.
+</step_3_generate>
+
+<step_4_verify>
+    **Role**: Independent Reviewer
+
+    **Verification checklist**:
+
+    | Check | Pass Criteria |
+    |:---|:---|
+    | File completeness | `screens/` contains `index.html` + `_shared.css` + all `S-XX.html` |
+    | Cross-file links | All `S-XX.html` links in `index.html` are valid; each `S-XX.html` has back-to-index link |
+    | CSS references | Each `S-XX.html` references `_shared.css`; CSS variables from design_tokens |
+    | State coverage | Each screen contains default + applicable states (loading/empty/error) |
+    | ui_context.md | Screen index routes reference `screens/S-XX.html` paths |
+    | (Incremental) Existing screens | Unmodified screen files were not overwritten |
+
+    Failed items → fix and recheck. All pass → proceed to step_5_signoff.
+</step_4_verify>
+
+<step_5_signoff>
+    **Pre-signoff Checklist** (confirm before output):
+    □ `screens/` directory structure complete (index.html + _shared.css + S-XX.html)
+    □ `ui_context.md` generated/updated with correct path references
+    □ Step 4 verification all passed
+    □ (Incremental) Only target screens modified, other files unchanged
+
+    **Output**: UI concept design summary:
+    - **Mode**: Full generation / Incremental update
+    - **Screen coverage**: N screens total (X new / Y updated / Z retained)
+    - **Aesthetic direction**: preset + brand color
+    - **File list**: Generated/modified files
+
+    **User confirmation**: Reply **OK** to finish; non-OK enters Refinement (calls Skill for partial update).
+
+    **Next Steps**:
+
+    | Priority | Action | Description |
+    |:---|:---|:---|
+    | Recommended | Open `screens/index.html` in browser | Verify layout and visual design |
+    | 1 | `/archi.plan <first pending task ID>` | Start planning tasks |
+</step_5_signoff>
+
+</protocol_ui>

package/dist/templates/en/docs/shared/ui-redlines.md

@@ -0,0 +1,7 @@
+**UI Design Red Lines (Anti-patterns)**:
+- **No purple-gradient-on-white** — AI default aesthetic signature
+- **No emoji as icons** (🔔📁⚙️) → use self-drawn SVG or declared icon library
+- **No identical centered-card layout for all screens** → list/detail/form must differ
+- **No pure-black + pure-white** → use layered grays
+- **No generic feel** → opening must instantly identify aesthetic (Linear vs Notion vs Grafana)
+- **No hardcoding** — use Tokens for colors, variables for spacing, no magic numbers

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

@@ -79,7 +79,7 @@ description: Task Specification for {FEATURE_NAME}.
 
 ## 5. Constraints
 
-<!-- [AI]: Extract red-line constraints relevant to this task from vision.md + 02_tech_stack.md.
+<!-- [AI]: Extract red-line constraints relevant to this task from vision.md + tech_stack.md.
 
   Format:
   - [constraint content] (ref: [source])

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

@@ -1,12 +1,12 @@
 ---
-description: Task-level UI scope declaration — screen IDs come from ui_context.md; visual prototype is ui_concept.html (for humans). Do not redefine global layout or navigation.
+description: Task-level UI scope declaration — describes the screens/component scope this task owns. Screen IDs from ui_context.md; visual prototype in screens/ (for humans).
 glue: Screen IDs referenced from [[__DOCS_DIR__]]/global/ui_context.md. Do not redefine global layout or navigation.
 ---
 
 # UI Scope: {FEATURE_NAME}
 
 > **Screen Index**: `[[__DOCS_DIR__]]/global/ui_context.md` (AI reads screen IDs and navigation graph)
-> **Visual Prototype**: `[[__DOCS_DIR__]]/global/ui_concept.html` (human browser preview)
+> **Visual Prototype**: `[[__DOCS_DIR__]]/global/screens/index.html` (human browser preview, individual screens at `screens/S-XX.html`)
 > **Tokens**: `[[__DOCS_DIR__]]/global/design_tokens.json`
 > **Protocol**: ITP v3.0 (scope limited to components within this task's boundary)
 
@@ -27,15 +27,15 @@ glue: Screen IDs referenced from [[__DOCS_DIR__]]/global/ui_context.md. Do not r
 ```text
 [ScreenName > modified area]
   NewComponent [Col, Gap:4]       ← added by this task
-    ExistingComponent             ← ref: ui_concept.html S-XX (no modification)
+    ExistingComponent             ← ref: screens/S-XX.html (no modification)
     #NewSubComponents
 ```
 
-> **Reference rule**: Components already defined in `ui_concept.html` → `ref: ui_concept.html#S-XX-ComponentName`; do not copy-paste their structure.
+> **Reference rule**: Components already defined in `screens/S-XX.html` → `ref: screens/S-XX.html#ComponentName`; do not copy-paste their structure.
 
 ## 3. Interactions (new interactions introduced by this task)
 
-<!-- [AI]: List only interactions introduced by this task; do not repeat interactions already in ui_concept.html -->
+<!-- [AI]: List only interactions introduced by this task; do not repeat interactions already in screens/S-XX.html -->
 
 | Trigger | Target | Action |
 |:---|:---|:---|
@@ -43,9 +43,9 @@ glue: Screen IDs referenced from [[__DOCS_DIR__]]/global/ui_context.md. Do not r
 
 ## 4. States (state rendering owned by this task)
 
-<!-- [AI]: If ui_concept.html already fully describes the states, this section may be omitted or only note deltas -->
+<!-- [AI]: If screens/S-XX.html already fully describes the states, this section may be omitted or only note deltas -->
 
-| State | Delta from ui_concept.html |
+| State | Delta from screens/S-XX.html |
 |:---|:---|
-| `loading` | Same as ui_concept.html S-XX loading (no delta) |
+| `loading` | Same as screens/S-XX.html loading (no delta) |
 | `empty` | Different copy for this task's empty state: "{specific copy}" |