architext 0.0.3 → 0.0.5

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

@@ -1,117 +1,78 @@
 <protocol_scope>
-  **Trigger**: `/archi.scope [file_path]`
+  **Trigger**: `/archi.scope [file_path]` | Auto-loaded by Workflow Dispatch on natural language trigger
   **Phase**: Requirement Decomposition
-  **Goal**: Read Scope Brief, decompose large requirements into multiple Roadmap tasks with dependency relationships.
+  **Goal**: Read Scope Brief, decompose large requirements into Roadmap tasks with dependencies.
 
 <meta>
     <style>Strategic, Analytical, Structured</style>
     <language>English</language>
     <principles>
-      1.  **Brief-Driven**: Use user-provided Scope Brief as primary input; never brainstorm tasks from scratch.
-      2.  **Incremental**: Append to existing Roadmap; never rewrite existing tasks.
-      3.  **User Agency First**: Adopt user-specified choices from Brief as-is; never question or replace.
-      4.  **Minimal Questions**: Only ask about information gaps; skip questioning if Brief is sufficient.
-      5.  **Option Z Everywhere**: All supplementary questions must include `[Z] Custom`.
+      1.  **Brief-Driven**: User-provided Scope Brief is the core input; no task brainstorming from thin air.
+      2.  **Incremental**: Append to existing Roadmap; do not rewrite existing tasks.
+      3.  **User Agency First**: User-filled choices in Brief must be adopted directly; do not question or replace.
+      4.  **Minimal Questions**: Ask only for information gaps; skip when Brief is sufficient.
+      5.  **Option Z Everywhere**: Supplementary questions must include `[Z] Custom`.
+      6.  **IDE-Native First**: Leverage IDE native capabilities to drive execution rhythm; this protocol defines quality standards and checkpoints, not fight IDE planning/execution mechanisms.
     </principles>
 </meta>
 
 <step_0_ingest>
     **Role**: Intelligence Analyst
     **Action**:
-    1. Parse `[file_path]` from trigger command:
+    1. Parse `[file_path]` from trigger:
        - If path provided → read that file
-       - If no path → look for `scope-brief.md` (project root), then `[[__DOCS_DIR__]]/scope-brief.md`
-       - If none found or empty → jump to `<fallback_interview>`
+       - If not provided → search `scope-brief.md` (project root), then `[[__DOCS_DIR__]]/scope-brief.md`
+       - If user entered via natural language description (no file_path param) and above files not found → goto `<fallback_interview>`
+       - If neither exists or empty → goto `<fallback_interview>`
 
-    2. Parse Brief sections and extract:
-       - Initiative name and description
-       - Task list
-       - Existing design decisions
-       - Boundaries & constraints (out of scope, timeline, dependencies, technical limits)
-       - Affected existing tasks
-       - References
+    2. Parse Brief sections, extract: initiative name and description, task list, pre-defined design decisions, boundaries and constraints, affected existing tasks, references.
 
-    > Brief is a one-time input file; user may delete it after processing.
+    > Brief is a one-time input file; user may delete after processing.
 
     **Output**: Internal summary (not shown to user), proceed to `<step_1_load>`.
 </step_0_ingest>
 
 <step_1_load>
-    **Role**: System Analyst
     **Action**:
-    1.  **Read Vision**: `[[__DOCS_DIR__]]/global/vision.md` — read North Star Metric and Boundaries sections only; skip remaining chapters.
-    2.  **Read Roadmap**: `[[__DOCS_DIR__]]/global/roadmap.json` — extract only `id/title/status/deps/tag` fields per task (skip `goal/notes`; requirement decomposition does not need these); read current max ID watermark for new task numbering.
-    3.  **Read Tech Stack**: `02_tech_stack.md` — technical constraints.
-    4.  **Read Map**: `[[__DOCS_DIR__]]/global/map.json` — read `directoryMapping` and `featureRelations` only; skip `logicalTopology` and `criticalUserJourneys`.
-    5.  **Scan Tasks**: Scan `[[__DOCS_DIR__]]/tasks/` directory — understand existing task summaries (title + key flows, no full read needed).
+    1.  **Load**: vision.md (North Star + Boundaries only), roadmap.json (id/title/status/deps/tag + max ID watermark only), 02_tech_stack.md, map.json (directoryMapping + featureRelations only).
+    2.  **Scan Tasks**: Scan tasks/ — understand existing task summaries (title + key flows; full read not needed).
 
     **Output**: Internal context summary, proceed to `<step_2_analysis>`.
 </step_1_load>
 
 <step_2_analysis>
     **Role**: Chief Product Strategist (CPO)
-    **Input**: Step 0 Brief parsing result + Step 1 project context.
+    **Input**: Step 0 Brief parse result + Step 1 project context.
 
     **Action**:
 
-    1. **Vision Alignment Check**: Does the Brief align with vision.md north star metrics? If deviation → flag `[Vision Deviation Warning]`.
-    2. **Task List Completeness**: Does the task list sufficiently support the initiative goal?
-    3. **Impact Assessment**: Brief "Affected Existing Tasks" → verify against roadmap/tasks for existence and status.
-    4. **Gap Identification**: Check Brief for critical missing information.
-    5. **Linkage Check**: Read `map.json.featureRelations`; semantically compare the new task's description against each `sources` field to determine if it falls within any aggregator's coverage. Surface a linkage reminder in the summary if matched.
+    1. **Vision alignment check**: Does Brief align with vision.md North Star? If deviation → mark `[Vision Deviation Warning]`.
+    2. **Task list completeness**: Sufficient to support initiative goal?
+    3. **Impact assessment**: Brief "affected existing tasks" → verify against roadmap/tasks.
+    4. **Gap identification**: Key info missing in Brief?
+    5. **Linkage check**: [[SUBAGENT: archi-feature-relations|mode: check, context: Compare new task descriptions with featureRelations sources; output linkage reminder if matched]][[NO-SKILL: (Skill not installed: read `[[__DOCS_DIR__]]/skills/archi-feature-relations/SKILL.md`, follow mode: check logic)]]
 
-    **Gap Levels**:
-    - **Required**: Missing prevents reasonable decomposition (e.g., empty task list)
-    - **Recommended**: AI can infer but should confirm (e.g., unclear dependencies)
-    - **Optional**: AI can decide autonomously (e.g., task grouping approach)
+    **Gap levels**: Required → cannot decompose | Can supplement → AI can derive, suggest confirm | Suggested → AI decides
 
-    **Decision**:
-    - No "Required" or "Recommended" gaps → skip Step 2.5, proceed to Step 3
-    - Has gaps → proceed to Step 2.5
+    **Decision**: No "Required" + "Can supplement" gaps → skip Step 3 | Has gaps → enter Step 3
 
-    **Output**: Display Brief analysis summary to user:
-    ```
-    ### SCOPE BRIEF Analysis Report
-    > **Initiative**: [Name] | **Scale**: Estimated [N] tasks
-
-    **Vision Alignment**: [Aligned / ⚠️ Deviation — reason]
-
-    **Confirmed Information**:
-    - [list]
-
-    **Affected Existing Tasks**:
-    | Task | Status | Estimated Impact |
-    |:---|:---|:---|
-    | [ID: Name] | [done/active/stub] | [needs modification/extension/no impact] |
-
-    **[?matched] Linkage Reminder**:
-    | Aggregator | checkNote |
-    |:---|:---|
-    | [aggregator ID/path] | [checkNote content] |
-
-    **Information Gaps** (to be addressed):
-    - [gap list]
-
-    **AI Will Auto-Decide** (no action needed):
-    - [list]
-    ```
+    **Output**: Output SCOPE BRIEF analysis report to user — include initiative name/estimated scale, Vision alignment, confirmed info, affected existing tasks table (task/status/estimated impact), (if matched) linkage reminder table, information gaps, AI auto-decide items. Enter step_3_supplementary (has gaps) or step_4_decompose (no gaps).
 </step_2_analysis>
 
-<step_2_5_supplementary>
-    **Role**: Product Consultant
-    **Trigger**: Only when Step 2 identifies "Required" or "Recommended" gaps.
+<step_3_supplementary>
+    **Trigger**: Only when Step 2 finds "Required" or "Can supplement" 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)]]
-</step_2_5_supplementary>
+    [[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_3_supplementary>
 
-<step_3_decompose>
+<step_4_decompose>
     **Role**: Chief Architect
-    **Input**: Full Brief + project context + supplementary answers (if any).
+    **Input**: Full Brief + project context + supplement 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 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):
+    **Display format** (convert Skill output to the following format, present to user, await confirmation):
 
     ```
     #### Phase 1: Infrastructure
@@ -120,79 +81,78 @@
     #### Phase 2: Core Features
     | ID | Title | Description Summary | Deps | Tag |
 
-    #### Execution Batches (Parallel Groups)
-    (Derived from deps via topological sort)
+    #### Execution Batches (parallel execution groups)
     Batch 1 (ready immediately): ...
-    Batch 2 (after Batch 1): ...
+    Batch 2 (after Batch 1 complete): ...
 
-    #### NFR Cross-Cutting Concerns (merged, not in Roadmap)
-    (From Skill's NFR merge list)
-    - [NFR name] → injected into [task ID] | affects: [other task IDs]
+    #### NFR cross-cutting concerns (merged, not in Roadmap)
+    - [NFR name] → inject [task ID] | affects: [other task IDs]
     ```
 
-    **Gate**: Proceed to step_4 only after user replies **OK**. Do not write to Roadmap without confirmation. User may refine the plan before confirming (merge/split/adjust deps).
-</step_3_decompose>
+    **Gate**: User replies **OK** to enter step_5_roadmap_update; do not write to Roadmap without confirmation.
+</step_4_decompose>
 
-<step_3_5_refinement>
-    **Role**: Consultant
-    **Trigger**: User replies non-OK, with merge/split/add/remove/dependency adjustments.
+<step_4_5_refinement>
+    **Trigger**: User reply is not OK — contains merge/split/add/remove/dependency adjustments.
     **Action**: Incorporate user feedback, refresh decomposition plan and re-output, await re-confirmation.
-</step_3_5_refinement>
+
+    User replies OK → enter step_5_roadmap_update.
+</step_4_5_refinement>
 
 <step_4_roadmap_update>
-    **Role**: System Administrator
     **Input**: User-confirmed decomposition plan.
 
     **Action**:
-    1.  Append new tasks to corresponding Phase's `tasks` array in `[[__DOCS_DIR__]]/global/roadmap.json`.
+    1.  Append new tasks to corresponding Phase's `tasks` array in roadmap.json.
     2.  If new Phase needed → append to `phases` array.
-    3.  Update `lastUpdated` field.
-    4.  [?New modules] Update `directoryMapping` in `[[__DOCS_DIR__]]/global/map.json`: pre-register inferred module paths for new tasks (based on tech_stack architecture pattern and task descriptions; directory-level only — details to be filled during `/archi.plan`).
+    3.  Update `lastUpdated`.
+    4.  (New modules) Update map.json `directoryMapping`: pre-register inferred module paths for new tasks.
 
-    **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 |
+    **Terminal Gate** (do not skip): Standard check (task --check + render).
+
+    **Output**: Write confirmation. Enter step_6_signoff.
+</step_5_roadmap_update>
 
-    **Output**: Write confirmation.
-</step_4_roadmap_update>
+<step_6_signoff>
+    **Pre-signoff Checklist** (confirm each item before Output):
+    □ Decomposition proposal confirmed by user (replied OK before writing to roadmap — step_4 Gate)
+    □ roadmap.json — tasks appended (not overwritten), lastUpdated updated
+    □ (new modules) map.json directoryMapping — new task module paths pre-registered
+    □ step_5 Terminal Gate — task --check + render passed
 
-<step_5_signoff>
-    **Action** (Gate must complete in step_4):
-    1.  Run `npx archi task` to display task progress overview.
+    **Action** (Gate must complete in step_5):
+    1.  Run `npx archi task` to output task progress overview.
     2.  Output summary.
 
     **Output**: Requirement decomposition summary, including:
-    - **Brief Source Confirmation**: Initiative name and core objective
-    - **New Tasks**: Count and phase distribution
-    - **Impact on Existing Tasks**: Impact list (if any)
+    - **Brief source confirmation**: Initiative name and core goal
+    - **New tasks**: Count and phase distribution
+    - **Impact on existing tasks**: Impact list (if any)
     - **Next Steps**:
 
-    | Priority | Action | Description |
+    | Priority | Action | Notes |
     |:---|:---|:---|
-    | [?UI] Recommended | Run `archi-ui-wireframe` Skill (append mode) | 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 |
+    | (UI projects only) 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` |
+    | 1 | `/archi.plan <first pending task ID>` | Deep-plan the first executable task |
     | 2 | Review roadmap | Confirm dependency relationships and priorities |
 </step_5_signoff>
 
 <fallback_interview>
-    **Trigger**: Brief file does not exist or is empty.
-    **Role**: Product Consultant
+    **Trigger**: Brief file not found or empty, or user entered via natural language description.
 
     **Action**:
-    1. Inform user that `scope-brief.md` was not found. Suggest:
-       - Run `npx archi template scope-brief` to fetch template to project root
+    1. Inform user that requirements will be gathered via conversation. Suggest:
+       - Run `npx archi template scope-brief` to get template to project root
        - Fill in and re-run `/archi.scope scope-brief.md`
-       - Or continue conversation to provide information via interview
-    2. If user chooses to continue conversation, guide in this order:
-       a. What do you want to build? (Initiative name, one-line description, motivation)
-       b. What tasks does it include? (Specific task list)
-       c. What constraints exist? (Out of scope, dependencies, technical limits)
-       d. Which existing tasks will be affected?
-    3. After collection, write information to `scope-brief.md` (project root), then jump to `<step_1_load>`.
-
-    > This mode is for backward compatibility; core flow remains Brief-driven.
+       - Or continue conversation and provide info via interview
+    2. If user chooses to continue, guide by the following dimensions (skip if already known, 1-2 questions each):
+       a. **Motivation & Goals**: Why build this? What problem does it solve? What outcome is expected?
+       b. **Scope**: Which features/modules are included? What's excluded?
+       c. **Task Breakdown**: Do you have a rough task split in mind? (If not, AI will decompose in step_3)
+       d. **Constraints**: Technical limits, time constraints, dependencies?
+       e. **Impact**: Which existing features will be affected?
+    3. After collection, write to `scope-brief.md` (project root), following scope-brief template structure.
+    4. Inform user brief is generated, then goto `<step_1_load>` to continue.
 </fallback_interview>
 
 </protocol_scope>