architext 0.0.2 → 0.0.4

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

@@ -104,7 +104,7 @@
     **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.]][[NO-SKILL: (Skill not installed: read `[[__DOCS_DIR__]]/skills/archi-interview-protocol/SKILL.md` and follow its rules)]]
 </step_2_supplementary>
 
 <step_3_constitution>
@@ -161,7 +161,7 @@
     - If user provided nothing, keep template default
 
     ### 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 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)]]
 
     ### 3.5 Other global docs (as needed)
     - `dictionary.json`: Extract domain terms from Brief
@@ -186,23 +186,17 @@
     **Output**: Write all files, then run `npx archi render` to generate visual `.md`.
 </step_3_constitution>
 
-<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?
+<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)]]
 
-    Silently fix issues; mark critical ones with `Risk Warning`.
-</step_4_audit>
+    [[INCLUDE: shared/verify-result-handling.md]]
+</step_4_verify>
 
 <step_4_5_ui_wireframe>
     **Trigger**: Only when project features include [?UI].
-    **Action**: Auto-invoke `archi-ui-wireframe` Skill (Phase 1 wireframe).
+    **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`

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])
+-->

package/dist/templates/en/skills/archi-data-sync/SKILL.md

@@ -0,0 +1,83 @@
+---
+name: archi-data-sync
+type: reviewer
+description: Data governance sync executor. In isolated context, scans main Agent output, compares with global data file state, performs incremental sync per 03_data_governance.md rules, returns change Diff.
+---
+
+# Data governance sync executor
+
+## System flow position
+
+```
+/archi.* step_N → Verify phase
+    ↓
+[This Skill] scans output → compare global files → incremental sync → return Diff
+    ↓
+Main Agent Signoff (confirm Diff)
+```
+
+> **Skill responsibility boundary**:
+> - Responsible: Scan main Agent output for new business entities/error codes/Schema, compare with global data files, perform incremental sync
+> - Not responsible: Modify `03_data_governance.md` itself (this Skill enforces rules, does not define them)
+> - Not responsible: Register framework concepts (Architext framework concepts must not be registered to global data files)
+
+---
+
+## Authoritative rule source
+
+`03_data_governance.md` is the single authoritative source for data governance. All behavior of this Skill must align with that file.
+
+---
+
+## Sync scope
+
+| Global file | Sync content | Trigger |
+|:---|:---|:---|
+| `dictionary.json` | New business entities · actions · shared tools · public components | Output contains unregistered business terms or tools |
+| `error_codes.json` | New business error codes | Output contains unregistered error scenarios |
+| 本任务涉及data时: `data_snapshot.json` | Schema changes | Output has data model add/modify |
+| 仅api项目: `api_snapshot.json` | New endpoints | Output has new HTTP/RPC endpoints |
+| 仅api项目: `env_registry.json` | New env vars | Output introduces new `process.env.X` |
+| 仅cli项目: `command_api.json` | New commands | Output has new CLI commands |
+| 仅lib项目: `public_api.json` | New public exports | Output has new public exports |
+
+---
+
+## Execution protocol
+
+1. **Read global data files**: Load global files matching project features from table above
+2. **Scan main Agent output**: Identify new business entities, error codes, Schema, endpoints, etc.
+3. **Boundary check**: Do not register framework concepts (scripts, scaffold, roadmap, plan, etc.); sync only project business domain content
+4. **Deduplication**: Compare with existing entries, avoid duplicate registration
+5. **Incremental sync**: Append/modify only, do not delete existing entries
+6. **Output change Diff**
+
+### Hard boundaries
+
+- **No direct append** — Must check existing content boundary before write, avoid duplicates or conflicts
+- **No framework concept registration** — Sync only project business domain content
+- **No modify `03_data_governance.md`** — This Skill enforces rules, does not define them
+
+### Output format
+
+```
+### Data Sync Results
+
+ADDED:
+- dictionary.json: entities += [new entity names]
+- error_codes.json: businessErrors += [ERR_CODE]
+
+MODIFIED:
+- data_snapshot.json: models.User += [new fields]
+
+NO CHANGE:
+- [files with no sync needed]
+
+**Summary**: X files changed / Y added / Z modified
+```
+
+When no sync needed: `### Data Sync Results — NO CHANGES`
+
+---
+
+> **Intermediate output**: This Skill is a review subprogram; after producing change Diff, control returns to caller.