architext 0.0.2 → 0.0.4

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

@@ -39,35 +39,55 @@
         - Execute only when a `ref: tasks/<dep_id>/spec.md#X` reference appears in the current spec/plan; skip if no reference found.
         - **Stub Compatibility**: If a dependency's Spec-Status is Stub, extract source files from the stub's "Associated Files", read entry files to extract public interfaces/exported types as upstream interface reference.
         - Avoid re-defining upstream interfaces; ensure integration points are precisely aligned.
+    7.  **Read Refs** (if any): Read `[[__DOCS_DIR__]]/refs/index.json` (if exists).
+        - Match relevant ref entries by tags and current task description semantics.
+        - Load only matched ref files (`[[__DOCS_DIR__]]/refs/{id}.{ext}`); skip unrelated entries.
+        - If `refs/index.json` does not exist or refs is empty → skip.
 
     **Output**: Present a **Task Context Brief** to the user:
     ```
     ### Task Context: [Task Name] ([ID])
 
+    **Task Type**: [Inferred from ID prefix: Infrastructure / Feature / Quality / Edit]
     **Goal**: [roadmap task's goal; highlight any [User Presets] if present]
     **Upstream Dependencies**: [completed dependency tasks and their key interfaces/types, or "None"]
     **Project Features**: [activated UI/Data/CLI/Lib/API tags]
     **Technical Constraints**: [key red lines from 02_tech_stack.md]
     **Design Philosophy**: [North Star Metric and design principles from vision.md]
     **Project Conventions**: [from 02_tech_stack.md §9 — Error Handling: X | Data Flow: X | Auth: X, or "Not set" if absent]
+    **External knowledge refs**: [matched ref ids, e.g. `wechat-pay`, `company-sdk`; or "None"]
     ```
     Retain full context materials internally, proceed to step_2.
 </step_1_load>
 
 <step_1_5_complexity>
     **Role**: Product Consultant
-    **Action**: Assess task complexity to decide whether to run the full step_2 flow:
+    **Action**: Detect task type, assess complexity, decide flow path.
 
-    **① Granularity hard-limit check (before complexity verdict)**:
+    **⓪ Task Type detection (execute first)**:
 
-    | Metric | Limit |
-    |:---|:---|
-    | Estimated spec.md Scenario count | ≤ 6 |
-    | Estimated plan.json Phase count | ≤ 4 |
+    Infer task type from `<ID>` prefix; applies to all subsequent steps:
+
+    | ID Prefix | Task Type | spec § 2 Primary Dimension | spec § 4 Interface Exports |
+    |:---|:---|:---|:---|
+    | `INF-` | Infrastructure | Structural (config contracts) | **Required** (downstream infrastructure) |
+    | `FEAT-` | Feature | Behavioral (behavior scenarios) | Required when has downstream deps |
+    | `POLISH-` | Quality | Quantitative (quality targets) | Usually omit |
+    | `EDIT-` | Edit | Inherit from original task | Inherit |
 
-    > Estimation method: based on the roadmap task goal and dependency context loaded in step_1, quickly enumerate the core behavior paths. Trigger if over the limit — no need for precise calculation.
+    > Mixed tasks (e.g. INF task with behavior aspect) may combine dimensions in § 2; use sub-headings to distinguish.
 
-    **② Complexity verdict (only after granularity passes)**:
+    **① Granularity hard-limit check (by Task Type)**:
+
+    | Task Type | Acceptance Criteria item cap | plan.json Phase cap |
+    |:---|:---|:---|
+    | Feature | ≤ 6 Scenarios | ≤ 4 |
+    | Infrastructure | ≤ 8 Contracts | ≤ 5 |
+    | Quality | ≤ 4 Targets | ≤ 3 |
+
+    > Estimation method: based on roadmap task goal and dependency context from step_1, quickly enumerate core paths. Trigger if over limit — no precise calculation needed.
+
+    **② Complexity verdict (after granularity passes)**:
 
     | Signal | Verdict | Flow |
     |:---|:---|:---|
@@ -76,9 +96,21 @@
 
     **Simple Mode**:
     - Skip 5-dimension architecture recommendations and User Confirm Gate
-    - spec condensed to 1-2 Gherkin scenarios
+    - spec condensed to 1-2 Acceptance Criteria items (format by Task Type)
     - plan condensed to a single Phase
     - Confirm at signoff (replacing step_2 Gate)
+
+    **③ Design signal detection (after Standard verdict)**:
+
+    For Standard tasks, detect whether to generate `design.md` (technical design):
+
+    | Signal | Verdict |
+    |:---|:---|
+    | Architecture option's AI- contains complexity warning (e.g. "extremely hard to implement correctly", "state management complex", "connection leak") | **Standard + Design** |
+    | Involves custom state machine, non-trivial algorithm, multi-component coordination protocol, retry/recovery strategy | **Standard + Design** |
+    | Standard CRUD / config / simple integration | **Standard** (no design.md) |
+
+    > When Standard + Design: step_2 must output mechanism preview (Part 1.5); step_4 must additionally generate `design.md`.
 </step_1_5_complexity>
 
 <step_2_interview>
@@ -114,9 +146,22 @@
 
     #### Part 2: Architecture Recommendations
 
-    [[SKILL: Follow `archi-plan-options` Skill's three-step selection logic (Convention Inheritance -> Tag Routing -> Recommend vs. Expand) to generate architecture recommendations across five dimensions.]][[NO-SKILL: (Skill not installed: read `[[__DOCS_DIR__]]/skills/archi-plan-options/SKILL.md` and follow its three-step logic)]]
+    [[SKILL: archi-plan-options|Follow the skill's three-step selection logic (Convention Inheritance -> Tag Routing -> Recommend vs. Expand) to generate architecture recommendations across five dimensions.]][[NO-SKILL: (Skill not installed: read `[[__DOCS_DIR__]]/skills/archi-plan-options/SKILL.md` and follow its three-step logic)]]
+
+    When expanding a Q-table, follow the format in [[SKILL: archi-interview-protocol|the skill's standard output format]][[NO-SKILL: (Skill not installed: read `[[__DOCS_DIR__]]/skills/archi-interview-protocol/SKILL.md` and follow its rules)]].
+
+    #### Part 1.5: Mechanism Preview [?Complex]
+
+    Output only when step_1_5 verdict is **Standard + Design**. List core mechanisms needing technical design and intended pattern:
+
+    ```
+    ### Mechanism Preview (will generate design.md)
+    | Mechanism | Pattern | Brief |
+    |:---|:---|:---|
+    | [name] | [State Machine / Pipeline / Decision Matrix / Protocol] | [one-sentence description] |
+    ```
 
-    When expanding a Q-table, follow the format in [[SKILL: `archi-interview-protocol` Skill's standard output format]][[NO-SKILL: `[[__DOCS_DIR__]]/skills/archi-interview-protocol/SKILL.md`]].
+    > User may add/remove mechanisms or change pattern selection here.
 
     #### Output Format
 
@@ -134,6 +179,12 @@
     | Error Handling | [Convention value] | Project Convention | ref: 02_tech_stack.md §9 |
     | ... | ... | ... | ... |
 
+    [Only when Standard + Design]:
+    ### Mechanism Preview (will generate design.md)
+    | Mechanism | Pattern | Brief |
+    |:---|:---|:---|
+    | ... | ... | ... |
+
     [Only expand option table for dimensions requiring user decision]:
     **[Q<n>] Question title**
     > Why user decision is needed (one sentence)
@@ -149,6 +200,7 @@
     > - Design correction: "Registration doesn't need email verification step"
     > - Dimension override: "Core Structure=C, Error Handling=B D"
     > - Question answer: "Q1=B"
+    > - Mechanism change: "Remove Pipeline, reconnection doesn't need that complexity"
     ```
 
     **⌨️ INPUT**: Reply **OK** to accept all; or free-text annotations for changes. No fixed format required.
@@ -171,77 +223,119 @@
 
     **Action Checklist**:
     1.  **`map.json`**: Register `[[__DOCS_DIR__]]/tasks/<ID>_<Slug>` in `directoryMapping`; define module responsibility and dependencies in `logicalTopology`.
-    2.  **`dictionary.json`**: Extract **project business** new terms from the proposal to fill `entities`/`verbs`; register new shared tools to `utilities`; register new public components to `components`.
-    3.  [?Data] **`data_snapshot.json`**: Add/modify Schema based on Core Structure recommendation. Prohibited from writing "TBD"; must write field names and types.
-    4.  **`error_codes.json`**: Register new **business** error codes based on Error Handling recommendation. Framework script errors are handled by exit code + stderr; prohibited from registration.
-    5.  **`map.json` featureRelations**: Determine if this task is an "aggregator" — i.e., its core responsibility is to **list, summarize, or dynamically reflect** a class of other tasks (e.g., "list all commands", "aggregate all page entries", "register all routes"). If yes, append one record to `featureRelations`:
-        ```json
-        {
-          "aggregator": "<this task ID or file path>",
-          "sources": "<one-sentence description of what is aggregated, e.g. 'all CLI command tasks'>",
-          "evidence": "<basis, e.g. 'spec.md §X states this task dynamically lists all Y-type tasks'>",
-          "checkNote": "When tasks of this type are added or removed, check whether <aggregator> needs to be updated"
-        }
-        ```
-        If not an aggregator, skip this step.
+    2.  **Data governance sync** (`dictionary.json` / `error_codes.json` / `data_snapshot.json` etc.): Per `03_data_governance.md` rules, incrementally sync new business terms, error codes, Schema from the proposal to corresponding global files.
+    3.  **`map.json` featureRelations**: [[SUBAGENT: archi-feature-relations|mode: register, context: Determine if this Task is aggregator; if yes, register featureRelations entry]][[NO-SKILL: (Skill not installed: read `[[__DOCS_DIR__]]/skills/archi-feature-relations/SKILL.md`, follow mode: register logic)]]
 
     **Output**: Change diffs of above files (brief).
 </step_3_global_sync>
 
 <step_4_generate>
     **Role**: Doc Engineer
-    **Input**: Confirmed Unified Proposal (task design + architecture recommendations) + updated global context.
+    **Input**: Confirmed Unified Proposal (task design + architecture recommendations) + updated global context + Task Type from step_1_5.
     **Action**: Generate standard docs under `[[__DOCS_DIR__]]/tasks/<ID>_<Slug>/`.
 
     **1. `spec.md`** (Mandatory):
     - Template: `templates/spec.template.md`.
-    - Convert confirmed task design and architecture recommendations to Gherkin Scenarios.
-    - Each Scenario must map to a concrete flow step or exception path from the task design; do not invent scenarios.
-    - If upstream task, must include explicit Interface/Type definitions.
+
+    **spec § 2 dimension format by Task Type**:
+
+    | Task Type | § 2 Primary Dimension | Format requirement |
+    |:---|:---|:---|
+    | Feature | Behavioral | Gherkin (Given/When/Then); each Scenario maps to concrete flow step or exception path from task design |
+    | Infrastructure | Structural | Configuration Contract per config file/service (Path + Key Settings + Constraints + Verify). Key Settings **must state concrete values**; no generic descriptions (e.g. "configure X") |
+    | Quality | Quantitative | Quality Target; each optimization goal has Metric + Baseline + Target + Verify |
+    | Edit | Inherit from original | Same as original task type |
+
+    > Mixed tasks use sub-headings in § 2 to distinguish dimensions (e.g. INF task with Behavioral subsection for hotkey behavior).
+
+    **spec § 4 Interface Exports**: INF tasks **required** (downstream infrastructure must declare exports); FEAT tasks required when has downstream deps.
+    **spec § 5 Constraints**: **Required** — extract relevant red lines from vision.md + 02_tech_stack.md.
+
+    **General rules**:
+    - Do not invent Acceptance Criteria; each must correspond to concrete content in task design.
+    - If upstream task, must include explicit Interface/Type definitions in § 4.
 
     **2. `ui.md`** [?UI]:
     - Template: `templates/ui.template.md`.
     - **With `ui_context.md` (primary path)**:
-      1. **UI Divergence Check** (required before writing `ui.md`): Compare the confirmed task design from step_2 against the screen inventory in `ui_context.md`:
+      1. **UI Divergence Check** (required before writing `ui.md`): Compare the confirmed task design from step_2 against the screen inventory in `ui_context.md`. [[SKILL: archi-ui-wireframe|Follow the skill protocol to handle UI divergence.]][[NO-SKILL: (Skill not installed: read `[[__DOCS_DIR__]]/skills/archi-ui-wireframe/SKILL.md` and follow its protocol)]]. Criteria and action:
 
          | Divergence type | Criteria | Action |
          |:---|:---|:---|
          | No divergence | Screen index matches design | Write `ui.md` directly, reference screen ID |
-         | Minor addition | New state / modal / local area, overall layout unchanged | Call `archi-ui-wireframe` Skill (Plan refinement mode) to update `ui_concept.html` + `ui_context.md`; note `MODIFIED: S-XX` in `ui.md` |
-         | Structural divergence | Layout restructure, new standalone screen, flow path change | **Pause** — present divergence summary to user, wait for **OK**, then call Skill to update `ui_concept.html` + `ui_context.md`, then write `ui.md` |
+         | Minor addition | New state / modal / local area, overall layout unchanged | Call skill (Plan refinement mode) to update `ui_concept.html` + `ui_context.md`; note `MODIFIED: S-XX` in `ui.md` |
+         | Structural divergence | Layout restructure, new standalone screen, flow path change | **Pause** — present divergence summary to user, wait for **OK**, then call skill to update `ui_concept.html` + `ui_context.md`, then write `ui.md` |
 
       2. After resolving divergence, fill in screen scope and delta components per `ui.template.md`.
     - **Without `ui_context.md` (fallback path)**: Write full ITP v3.0 component tree, referencing `design_tokens.json` token definitions.
 
-    **3. `plan.json`** (Mandatory):
+    **3. `design.md`** [?Complex]:
+    - Template: `templates/design.template.md`.
+    - Generate only when step_1_5 verdict is **Standard + Design**.
+    - § 2 Core Mechanisms: Per step_2 confirmed mechanism preview, call [[SKILL: archi-design-patterns|skill's pattern selection guide and standard format to generate mechanism descriptions and run self-checks]][[NO-SKILL: (Skill not installed: read `[[__DOCS_DIR__]]/skills/archi-design-patterns/SKILL.md` and follow its pattern formats and self-check lists)]].
+    - § 3 Parameters: All mechanism numeric values must be concrete; no vague descriptions.
+    - § 4 Invariants: Each must be testable; must map to plan.json test entries.
+    - § 5 Failure Modes: Each failure must have detection + fallback behavior.
+    - § 6 Trace Verification: Trace design path from each spec § 2 AC; fix gaps by returning to § 2 or § 5.
+
+    **4. `plan.json`** (Mandatory):
     - Template: `templates/plan.template.json`.
     - Dynamically adjust Phases by project type; ensure each Task's context is self-contained.
     - Task descriptions explicitly state "Additive Only" + "Respect Unknowns".
-    - **`decisions`**: Fill per dimension; `choice` supports multi-select (e.g. `A B`, space-separated), custom (`Z: …`); `rationale` must explain reasoning for code phase; do not leave empty.
-    - **`notes`**: Fill each task's `notes` with: `[scope] · [spec ref] · [key constraints] · Verify: [concrete operation]`; used by `/archi.code` step_4 to locate context and run e2e; do not leave empty.
-      > Example: `Implement POST /auth/login · spec §3.1 · JWT must not contain password · Verify: curl POST /auth/login returns 200 + token field`
+
+    **WBS decomposition three principles (must follow when generating plan.json)**:
+
+    **Principle 1 — Deliverable-oriented**: Each task `title` describes **deliverable** not activity.
+    > ✅ Good: `apps/web/tsconfig.json — strict + path aliases`
+    > ❌ Bad: `Configure TypeScript`
+
+    **Principle 2 — 100% coverage**: After generation, verify coverage:
+    | Check | Rule |
+    |:---|:---|
+    | Each spec § 2 Acceptance Criteria item | Must have ≥1 task covering it |
+    | Each spec § 4 Interface Export | Must have task responsible for creating/exposing it |
+    | Each spec § 5 Constraint | Must be referenced in some task's notes |
+    Add tasks until 100% covered.
+
+    **Principle 3 — Granularity and mutual exclusion**:
+    | Signal | Verdict |
+    |:---|:---|
+    | Task involves ≥3 unrelated files | Too coarse — split |
+    | Task title cannot map to concrete output file | Too abstract — concretize |
+    | Two tasks modify same file same region | Violates mutual exclusion — merge or redraw boundary |
+    | Task notes single sentence with no verification | Insufficient info — supplement |
+
+    **`decisions` quality standard**:
+    - `rationale` **must include implementation guidance**; not only "why choose" but "how to configure after choosing".
+    > ✅ Good: `pnpm workspace manages apps/ + packages/; Turborepo pipeline: build→lint→type-check three-level cache; root scripts unified entry`
+    > ❌ Bad: `Brief explicitly requires` ← zero implementation guidance
+
+    **`notes` quality standard**:
+    - Format: `[output file path or operation target] · [spec ref] · [key constraints] · Verify: [executable command + expected result]`
+    - Used by `/archi.code` step_4 to locate and run e2e; do not leave empty.
+    > ✅ Good: `Create apps/web/next.config.ts · spec §2.2 · transpilePackages: ['@repo/ui'], output: 'standalone' · no CSS-in-JS · Verify: pnpm --filter web build succeeds (exit 0)`
+    > ❌ Bad: `Configure Next.js · spec §2.2` ← no concrete content, constraints, or verification
+    > ❌ Bad: `Create file · spec §2.1 · Verify: check file exists` ← "check file exists" not executable
+    > **Red Flag**: notes degenerate to title synonym. Each notes must contain information **not present** in title.
+
     - Run `npx archi render` after generation to produce readable `.md` view.
 </step_4_generate>
 
-<step_5_audit>
-    **Role**: Chief Auditor
-    **Checklist**:
-    1.  **Design Fidelity**: Do Scenarios fully cover confirmed task design (flow steps and exception paths)?
-    2.  **Tech Consistency**: Any undeclared tech used?
-    3.  **Data Integrity**: Do Scenario entities match confirmed core entities?
-    4.  **Error Handling**: Is Error Handling recommendation covered?
-    5.  **AX Compliance**: Are Anti-Clobbering and Interface Stability rules followed?
+<step_5_verify>
+    **Role**: Independent Reviewer
+
+    [[SUBAGENT: archi-silent-audit|mode: plan-docs, context: Review step_4 generated docs (spec.md, ui.md, plan.json, design.md)]][[NO-SKILL: (Skill not installed: read `[[__DOCS_DIR__]]/skills/archi-silent-audit/SKILL.md`, follow mode: plan-docs review dimension table item by item)]]
 
-    Silently fix issues; mark critical issues with `⚠️ Risk Warning`.
-</step_5_audit>
+    [[INCLUDE: shared/verify-result-handling.md]]
+</step_5_verify>
 
 <step_6_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 task <ID> --status active` | Task marked as in-progress |
-    | 3 | `npx archi render` | `.md` views generated |
+    | 2 | `npx archi render` | `.md` views generated |
+    | 3 | `npx archi task <ID> --status active` | Task marked as in-progress |
 
     **Action** (After Gate passes):
     1.  Output summary.

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

@@ -0,0 +1,63 @@
+<protocol_recover>
+**Trigger**: `/archi.recover <pack-file>`
+**Goal**: Read the pack file and write all user data (docs, tasks, custom rules) to their corresponding paths in the current project, completing data restore after a framework upgrade.
+
+<meta>
+  <style>Precise, Efficient, Non-interactive</style>
+  <language>English</language>
+  <principles>
+    1. **User Data Only**: The pack file contains only user data (`global/`, `tasks/`, `scripts/`, custom rules) — no framework files. Write all entries without filtering.
+    2. **Overwrite Always**: If the target file already exists, overwrite it directly without prompting (in an upgrade scenario, existing files are empty templates and safe to replace).
+    3. **Delta Notation**: Label each written file as `ADDED` or `MODIFIED` in the output.
+    4. **No Partial Write**: If any file write fails, stop immediately and report. Already-written files are not rolled back (idempotent — safe to re-run).
+  </principles>
+</meta>
+
+<step_1_ingest>
+  **Role**: Intelligence Analyst
+  **Action**:
+  1. Read the file at the `<pack-file>` path.
+  2. Parse the XML; extract the `path` attribute and CDATA content of each `<file>` element under `<files>`.
+
+  | Condition | Action |
+  |:---|:---|
+  | File not found or unreadable | Stop — ask user to verify path; suggest running `archi pack` to regenerate |
+  | XML malformed | Stop — note file may be corrupted; suggest re-running `archi pack` |
+  | `<files>` is empty | Stop — inform user the pack is empty |
+
+  **Output**: Internal file list (path + content). Do not output to user.
+</step_1_ingest>
+
+<step_2_apply>
+  **Role**: Senior Engineer
+  **Action**:
+  1. For each `<file>` entry:
+     - Use the `path` attribute (relative to project root) as the write target.
+     - If the target file exists → overwrite (mark as `MODIFIED`).
+     - If the target file does not exist → create (mark as `ADDED`).
+     - Write the full CDATA content, preserving original line endings and encoding.
+  2. Note: paths in the pack may contain nested subdirectories (e.g. `tasks/FEAT-001_auth/spec.md`); ensure parent directories exist before writing.
+
+  **Output**:
+  ```
+  ADDED     .architext/global/vision.md
+  ADDED     .architext/global/roadmap.json
+  ADDED     .architext/tasks/FEAT-001_auth/spec.md
+  MODIFIED  .cursor/rules/90_custom_rules.mdc
+  ...
+  ```
+</step_2_apply>
+
+<step_3_signoff>
+  **Action**:
+  1. Output restore summary:
+     - Total files written (ADDED and MODIFIED counted separately)
+  2. Next Steps:
+
+  | Step | Notes |
+  |:---|:---|
+  | Verify framework state | Run `/archi.help` to check project status and recommended next actions |
+  | Clean up pack file | You may delete `<pack-file>` — it is no longer needed |
+</step_3_signoff>
+
+</protocol_recover>

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

@@ -0,0 +1,258 @@
+<protocol_ref>
+**Trigger**: `/archi.ref <sub> [args]`
+**Goal**: Manage external knowledge references (third-party APIs, internal SDKs, business rules, etc.), store them in `refs/` in a structured way, and inject context into `plan`/`code` on demand.
+
+**Subcommands**:
+| Subcommand | Format | Purpose |
+|:---|:---|:---|
+| `add` | `/archi.ref add [input]` | Summarize and store external knowledge (core) |
+| `list` | `/archi.ref list` | List all stored references |
+| `update` | `/archi.ref update <id>` | Re-summarize a specified reference |
+| `remove` | `/archi.ref remove <id>` | Remove a specified reference |
+
+<meta>
+  <style>Analytical, Precise, Context-Aware</style>
+  <language>English</language>
+  <principles>
+    1. **Summarize, Not Copy**: Do not copy full original content; distill into structured summaries (key interfaces / constraints / examples) for efficient AI use, compression ratio ≥ 50%.
+    2. **Format-Aware**: Choose the most suitable carrier format (`.md` / `.json` / `.yaml`) based on content type, preserving semantic advantages of the original format.
+    3. **Tag-Driven**: Each ref must carry tags for `plan`/`code` to match and inject on demand; no tagless references allowed.
+    4. **Index-First**: All operations must sync with `refs/index.json`; AI loads on demand via index, no full scan.
+  </principles>
+</meta>
+
+<!-- ─── Format selection rules ─── -->
+<format_selection>
+  **Format-Aware rules** (referenced during step_3_store):
+
+  | Content type | Recommended format | Rationale |
+  |:---|:---|:---|
+  | Web page / URL / PDF / plain text | `.md` | Structured summary, highest AI read efficiency |
+  | OpenAPI / Swagger spec | `.yaml` | Preserve machine-readable structure; do not convert to .md |
+  | JSON Schema / config files | `.json` | Original structured data format is optimal |
+  | Mixed (with many code examples) | `.md` (with code blocks) | Preserve syntax in code blocks, add explanatory context |
+  | User pasted (pure Markdown) | `.md` | Store in same format, may refine |
+</format_selection>
+
+<!-- ═══════════════════════════════════════════════ -->
+<!--                   ADD subcommand               -->
+<!-- ═══════════════════════════════════════════════ -->
+
+<sub_add>
+
+<step_0_ingest>
+  **Role**: Intelligence Analyst
+  **Trigger**: `/archi.ref add [input]`
+  **Action**: Parse `[input]` to determine input source.
+
+  | input form | Handling |
+  |:---|:---|
+  | Local file path (e.g. `./docs/api.yaml`) | Read file content, record `sourceType: local-file` |
+  | URL (e.g. `https://...`) | Fetch page content, record `sourceType: url` |
+  | Not provided (conversation mode) | Ask user to paste content or provide path/URL, wait for input, record `sourceType: manual` |
+
+  Check if `[[__DOCS_DIR__]]/refs/index.json` exists:
+  - Exists → Read, get existing id list (avoid duplicate names)
+  - Not exists → Initialize as `{ "refs": [] }`
+
+  **Output**: Internal (raw content + sourceType + existing id list), proceed to `<step_1_analyze>`.
+</step_0_ingest>
+
+<step_1_analyze>
+  **Role**: System Analyst
+  **Action**:
+  1. **Content type identification**: Determine which type the raw content belongs to (see `<format_selection>`), decide recommended storage format.
+  2. **Key info extraction**: From content extract:
+     - Core interfaces/endpoints/function signatures
+     - Parameter list and types (input/output)
+     - Important constraints, limits, caveats
+     - Auth/authorization (if any)
+     - Typical usage examples (≤ 3)
+  3. **Info gap identification**:
+     - id naming (infer a candidate, e.g. `wechat-pay`, pending user confirmation)
+     - tags (infer from standard tags: `api` / `sdk` / `internal` / `payment` / `auth` / `map` / `notification` / `storage` / custom)
+     - Focus areas (if content is large, confirm which interfaces/features user cares about)
+
+  **Output**: Internal analysis summary, proceed to `<step_2_interview>` (if gaps) or directly `<step_3_store>` (if complete).
+</step_1_analyze>
+
+<step_2_interview>
+  **Role**: Product Consultant
+  **Trigger**: Execute only when id / tags / focus is uncertain.
+  **Action**: Ask user questions, max 3 questions, prefer multiple choice.
+
+  **Output format**:
+  ```
+  ### Reference info confirmation
+
+  **Content type**: [identified] → will store as [.md / .yaml / .json]
+  **Content summary**: [one-sentence description of raw content]
+
+  **Q1 — Reference ID** (for file naming and reference):
+  [A] [AI-inferred candidate] (recommended)
+  [B] Custom
+
+  **Q2 — Tags** (multi-select):
+  [A] api  [B] sdk  [C] internal  [D] payment  [E] auth  [F] Other: ___
+
+  (If content is large) **Q3 — Focus**:
+  [A] Keep full  [B] Keep only [specific interface list]  [C] Custom
+
+  **INPUT**: Q1 answer | Q2 answer | Q3 answer (if any)
+  ```
+
+  **Gate**: Wait for user reply before `<step_3_store>`.
+</step_2_interview>
+
+<step_3_store>
+  **Role**: Senior Engineer
+  **Action**:
+  1. Determine storage params:
+     - `id`: User-confirmed value (or AI-inferred)
+     - `format`: File extension from `<format_selection>` rules
+     - `filename`: `{id}.{format}`
+     - `tags`: User-confirmed tags list
+
+  2. **Generate ref file content** (by format):
+
+     **`.md` format skeleton**:
+     ```markdown
+     ---
+     id: {id}
+     title: {title}
+     tags: [{tags}]
+     sourceType: url | local-file | manual
+     source: {source path or URL, "manual-input" when manual}
+     created: {YYYY-MM-DD}
+     updated: {YYYY-MM-DD}
+     ---
+
+     ## Core info
+     <!-- Base URL, version, auth, etc. -->
+
+     ## Key interfaces
+     | Interface/Function | Path/Signature | Description |
+     |:---|:---|:---|
+
+     ## Important constraints and caveats
+
+     ## Examples
+     <!-- ≤ 3 most representative examples -->
+     ```
+
+     **`.yaml` format**: Store original OpenAPI/Swagger content (trim redundant example fields in responses, keep schema structure).
+
+     **`.json` format**: Store original JSON Schema or config (remove comments, keep structure).
+
+  3. **Write file**: `[[__DOCS_DIR__]]/refs/{id}.{ext}`
+
+  4. **Update index**: Append to `[[__DOCS_DIR__]]/refs/index.json` refs array:
+     ```json
+     {
+       "id": "{id}",
+       "title": "{title}",
+       "tags": ["{tags}"],
+       "format": "{ext}",
+       "file": "{id}.{ext}",
+       "sourceType": "url | local-file | manual",
+       "updatedAt": "{YYYY-MM-DD}"
+     }
+     ```
+
+  **Output**:
+  ```
+  ADDED  [[__DOCS_DIR__]]/refs/{id}.{ext}
+  MODIFIED  [[__DOCS_DIR__]]/refs/index.json
+  ```
+</step_3_store>
+
+<step_4_signoff_add>
+  **Output**: Add summary including:
+  - **Reference ID**: `{id}`
+  - **Storage format**: `{ext}` — rationale (one sentence)
+  - **Tags**: `[tags]`
+  - **File path**: `[[__DOCS_DIR__]]/refs/{id}.{ext}`
+  - **How to use**:
+
+  | Scenario | Description |
+  |:---|:---|
+  | `/archi.plan <ID>` | When planning involves `[tags]`-related features, AI auto-reads this ref |
+  | `/archi.code <ID>` | Injected as supplementary context during coding, provides interface signatures and constraint details |
+  | Manual reference | Mention "see `refs/{id}`" in conversation |
+</step_4_signoff_add>
+
+</sub_add>
+
+<!-- ═══════════════════════════════════════════════ -->
+<!--                  LIST subcommand               -->
+<!-- ═══════════════════════════════════════════════ -->
+
+<sub_list>
+
+**Role**: System Analyst
+**Trigger**: `/archi.ref list`
+**Action**: Read `[[__DOCS_DIR__]]/refs/index.json`.
+
+| Condition | Handling |
+|:---|:---|
+| Index missing / refs empty | Prompt "No references yet, run `/archi.ref add` to add the first" |
+| Normal | Display grouped by tags |
+
+**Output**:
+```
+### External knowledge references (N total)
+
+#### [tag group name]
+| ID | Title | Format | Updated |
+|:---|:---|:---|:---|
+| wechat-pay | WeChat Pay V3 API | .md | 2025-01-15 |
+| openapi-spec | Internal service OpenAPI | .yaml | 2025-01-10 |
+```
+
+</sub_list>
+
+<!-- ═══════════════════════════════════════════════ -->
+<!--                 UPDATE subcommand             -->
+<!-- ═══════════════════════════════════════════════ -->
+
+<sub_update>
+
+**Role**: Senior Engineer
+**Trigger**: `/archi.ref update <id>`
+**Action**:
+1. Find `<id>` in `index.json`, get `file` and `sourceType`.
+2. If `sourceType` is `url` → re-fetch original URL; `local-file` → re-read file; `manual` → prompt user to paste new content.
+3. Re-run `<step_1_analyze>` + `<step_3_store>` (keep original id/tags/format, only refresh content and `updatedAt`).
+
+| Condition | Handling |
+|:---|:---|
+| id not in index.json | Stop — prompt to check id, run `/archi.ref list` to view |
+
+</sub_update>
+
+<!-- ═══════════════════════════════════════════════ -->
+<!--                 REMOVE subcommand             -->
+<!-- ═══════════════════════════════════════════════ -->
+
+<sub_remove>
+
+**Role**: System Administrator
+**Trigger**: `/archi.ref remove <id>`
+**Action**:
+1. Find and remove `<id>` from `index.json`.
+2. Delete corresponding `refs/{id}.{ext}` file.
+3. Update `index.json`.
+
+**Output**:
+```
+REMOVED  [[__DOCS_DIR__]]/refs/{id}.{ext}
+MODIFIED  [[__DOCS_DIR__]]/refs/index.json
+```
+
+| Condition | Handling |
+|:---|:---|
+| id not found | Stop — prompt to check id, run `/archi.ref list` to view |
+
+</sub_remove>
+
+</protocol_ref>

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

@@ -120,7 +120,7 @@
     **Phase 2 — Cascade Update Task Docs**:
     For each affected Task, follow `/archi.edit` standards:
     1.  Update `spec.md` (logic/rules that need adjustment due to global changes).
-    2.  [?UI] Update `ui.md` (scope/interaction adjustments due to global changes); if screen structure is affected, run `archi-ui-wireframe` Skill (incremental update mode) to sync both `ui_concept.html` + `ui_context.md`.
+    2.  [?UI] Update `ui.md` (scope/interaction adjustments due to global changes); if screen structure is affected, [[SKILL: archi-ui-wireframe|run skill (incremental update mode) to sync both `ui_concept.html` + `ui_context.md`]][[NO-SKILL: (Skill not installed: read `[[__DOCS_DIR__]]/skills/archi-ui-wireframe/SKILL.md` and follow its protocol)]].
     3.  Append new Phase to `plan.json` `phases`: `Phase X: Global Revision — [Change Topic] (<Date>)`, listing implementation tasks.
 
     **Output**: Change summary for each file (global + Task).

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

@@ -102,14 +102,14 @@
     **Trigger**: Only when Step 2 identifies "Required" or "Recommended" gaps.
     **Input**: Step 2 gap list. Max 3 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.]][[NO-SKILL: (Skill not installed: read `[[__DOCS_DIR__]]/skills/archi-interview-protocol/SKILL.md` and follow its rules)]]
 </step_2_5_supplementary>
 
 <step_3_decompose>
     **Role**: Chief Architect
     **Input**: Full Brief + project context + supplementary answers (if any).
 
-    **Action**: [[SKILL: Follow the `archi-decompose-roadmap` Skill protocol to generate incremental task data from the Scope Brief task list]][[NO-SKILL: (Skill not installed: read `[[__DOCS_DIR__]]/skills/archi-decompose-roadmap/SKILL.md` and follow its protocol)]]
+    **Action**: [[SKILL: archi-decompose-roadmap|Follow the skill protocol to generate incremental task data from the Scope Brief task list.]][[NO-SKILL: (Skill not installed: read `[[__DOCS_DIR__]]/skills/archi-decompose-roadmap/SKILL.md` and follow its protocol)]]
 
     **Display format** (convert Skill output into the following format, present to user and await confirmation):
 
@@ -171,7 +171,7 @@
 
     | Priority | Action | Description |
     |:---|:---|:---|
-    | [?UI] Recommended | Run `archi-ui-wireframe` Skill (append mode) | Append screens for new tasks to `ui_concept.html`, sync `ui_context.md` |
+    | [?UI] Recommended | [[SKILL: archi-ui-wireframe|Run skill (append mode)]][[NO-SKILL: (Skill not installed: read `[[__DOCS_DIR__]]/skills/archi-ui-wireframe/SKILL.md` and follow its protocol)]] | Append screens for new tasks to `ui_concept.html`, sync `ui_context.md` |
     | 1 | `/archi.plan <first pending task ID>` | Deep planning for the first actionable task |
     | 2 | Review roadmap | Confirm dependency relationships and priorities |
 </step_5_signoff>