architext 0.0.2 → 0.0.4

package/dist/templates/en/docs/global/api_snapshot.json

@@ -0,0 +1,24 @@
+{
+  "endpoints": [
+    {
+      "method": "[GET | POST | PUT | DELETE | PATCH]",
+      "path": "[/resource/:id]",
+      "description": "[One-sentence endpoint responsibility]",
+      "auth": "[required | public | optional]",
+      "requestBody": "[Schema description or N/A]",
+      "responses": {
+        "200": "[Success response structure]",
+        "[4xx]": "[ref: error_codes.json#ERR_CODE]"
+      },
+      "owner": "[FEAT-xxx | INF-xxx]"
+    }
+  ],
+  "protocolMapping": [
+    {
+      "statusCode": "[400 | 401 | 403 | 404 | 500 | ...]",
+      "code": "[ERR_CODE]",
+      "meaning": "[Meaning]",
+      "action": "[Caller behavior: Toast / Redirect / Retry / ...]"
+    }
+  ]
+}

package/dist/templates/en/docs/global/command_api.json

@@ -0,0 +1,26 @@
+{
+  "commands": [
+    {
+      "name": "[command-name]",
+      "aliases": ["[alias]"],
+      "description": "[One-sentence command responsibility]",
+      "args": [
+        {
+          "name": "[arg-name]",
+          "required": true,
+          "description": "[Argument description]"
+        }
+      ],
+      "flags": [
+        {
+          "name": "--[flag-name]",
+          "short": "-[f]",
+          "type": "[string | boolean | number]",
+          "default": "[Default or null]",
+          "description": "[Flag description]"
+        }
+      ],
+      "owner": "[FEAT-xxx | INF-xxx]"
+    }
+  ]
+}

package/dist/templates/en/docs/global/env_registry.json

@@ -0,0 +1,12 @@
+{
+  "variables": [
+    {
+      "name": "[ENV_VAR_NAME]",
+      "required": true,
+      "default": null,
+      "description": "[Purpose]",
+      "example": "[Example value]",
+      "owner": "[FEAT-xxx | INF-xxx]"
+    }
+  ]
+}

package/dist/templates/en/docs/global/map.json

@@ -81,6 +81,11 @@
       "category": "UI/UX",
       "purpose": "Task-level UI scope declaration — references screen IDs from ui_context.md to define this task's screen/component scope"
     },
+    {
+      "file": "design.md",
+      "category": "Technical Design",
+      "purpose": "[?Complex] Technical design — state machine/pipeline/protocol definitions, parameter table, invariants"
+    },
     {
       "file": "plan.json",
       "category": "Plan",

package/dist/templates/en/docs/global/public_api.json

@@ -0,0 +1,12 @@
+{
+  "exports": [
+    {
+      "name": "[exportName]",
+      "type": "[function | class | type | constant | enum]",
+      "signature": "[TypeScript signature]",
+      "description": "[One-sentence export responsibility]",
+      "stability": "[stable | experimental | deprecated]",
+      "owner": "[FEAT-xxx | INF-xxx]"
+    }
+  ]
+}

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

@@ -24,20 +24,22 @@
 
         | Status | Handling |
         |:---|:---|
-        | `active` 🟢 | Pass, continue |
-        | `pending` ⏳ | Reject — prompt to run `/archi.plan <ID>` first |
-        | `blocked` 🧱 | Reject — prerequisites not completed |
-        | `done` ✅ | Reject — already completed, use `/archi.edit <ID>` for modifications |
+        | `active` | Pass, continue |
+        | `pending` | Reject — prompt to run `/archi.plan <ID>` first |
+        | `blocked` | Reject — prerequisites not completed |
+        | `done` | Reject — already completed, use `/archi.edit <ID>` for modifications |
 
     3.  **Load Context** (Use Roadmap `📁 Slug` to locate):
         - `[[__DOCS_DIR__]]/tasks/<id>_<Slug>/spec.md` — Logic & Scenarios
         - `[[__DOCS_DIR__]]/tasks/<id>_<Slug>/ui.md` — task UI scope declaration (if exists)
+        - [?Complex] `[[__DOCS_DIR__]]/tasks/<id>_<Slug>/design.md` — Technical design (if exists): state machine/pipeline/protocol definitions, parameter table, invariants
         - [?UI] `[[__DOCS_DIR__]]/global/ui_context.md` — AI screen index (screen IDs / routes / states / navigation graph / shared components)
         - [?UI] `[[__DOCS_DIR__]]/global/ui_concept.html` — read-only visual reference (calibrate layout against this during implementation; do not redesign — design is already locked in ui.md)
         - `[[__DOCS_DIR__]]/tasks/<id>_<Slug>/plan.json` — Task breakdown (contains `notes` shorthand; must reference during execution)
         - `02_tech_stack.md` — Technical Red Lines
         - [?UI] `[[__DOCS_DIR__]]/global/design_tokens.json`
         - [?Data] `[[__DOCS_DIR__]]/global/data_snapshot.json`
+        - **Read Refs** (if any): Read `[[__DOCS_DIR__]]/refs/index.json` (if exists); match by tags and spec.md tech domain semantics; load only matched ref files as supplementary context; skip if `refs/` missing or empty.
 
     **Output**: Atomic list of tasks to implement, marking dependencies and order.
 </step_1_resolve>
@@ -65,6 +67,7 @@
     - **Code Organization**: Follow the architecture pattern and file placement strategy defined in `02_tech_stack.md`.
     - **Comments**: Explain Why, not What; reject nonsense comments.
     - **Naming**: Self-documenting names; reject `a`, `b`, `tmp` etc. (except loop variable `i`).
+    - [?Complex] **Design Adherence**: When `design.md` exists, implementation must strictly follow its state machine/pipeline/protocol definitions; parameters must reference design.md § 3 values (no hardcoding other values); must satisfy all § 4 Invariants (use assert or runtime checks).
     - **Error Handling**: Prohibit swallowing errors/silent failures; must properly propagate errors and provide observable feedback to callers (UI: Toast; CLI: Exit Code; API: Status Code + Body).
     - **Robustness**: Explicitly handle edge cases (Loading/Error/Empty/Timeout); prohibit writing only Happy Path.
     - **SOTA**: Follow tech_stack best practices; reject explicitly forbidden outdated patterns.
@@ -112,30 +115,20 @@
     **Output**: ✅/❌ status and reason for each check; Task Verification evidence.
 </step_4_validate>
 
-<step_5_audit>
-    **Role**: Chief Auditor
-    **Checklist**:
-    1.  **Tech Consistency**: Consistent with `02_tech_stack.md` (libraries/patterns/API style).
-    2.  [?UI] **Design Compliance**: Styles use Token/Preset visual patterns only; no hardcoded magic values.
-    3.  [?Data] **Data Integrity**: Compliant with `data_snapshot.json`; field names/types match.
-    4.  **SOTA**: Reject outdated patterns; adopt tech_stack best practices.
-    5.  [?UI] **Accessibility**: Include necessary accessibility attributes.
-    6.  [?I18n] **I18n**: No hardcoded strings; must use Key/dictionary reference.
-    7.  **Performance**: Avoid unnecessary large dependencies/full imports/useless computation/memory leaks.
-    8.  **Security**: No sensitive info leakage; inputs validated.
-    9.  **Static Check Zero**: All static check issues resolved.
-    10. **step_4 Gate**: Confirm all step_4 checks (Static + Test + Task Verification) have passed.
-    11. **Linkage Check**: Read the `featureRelations` array from `[[__DOCS_DIR__]]/global/map.json`; semantically compare the current task against each `sources` field. If matched, output: `⚠️ Linkage: [aggregator] — [checkNote]`, reminding to confirm whether the aggregator needs to be updated after this implementation. Skip if `featureRelations` is empty.
-    12. **Data Governance**: When this implementation introduces new content, directly write to the corresponding global index:
-
-        | Trigger | File | Action |
-        |:---|:---|:---|
-        | New business entity · verb · shared utility | `dictionary.json` | Directly append |
-        | New error scenario | `error_codes.json` | Directly append |
-        | [?Data] Schema actually changed | `data_snapshot.json` | Directly sync |
-
-    Detail issues can be Auto-Fixed with explanation; major risks marked `⚠️ Risk` with alternatives proposed.
-</step_5_audit>
+<step_5_verify>
+    **Role**: Independent Reviewer
+
+    **5A. Code quality review**:
+    [[SUBAGENT: archi-silent-audit|mode: code-impl, context: Review step_3 implemented code (Tech/SOTA/Security/Performance + conditional dimensions)]][[NO-SKILL: (Skill not installed: read `[[__DOCS_DIR__]]/skills/archi-silent-audit/SKILL.md`, follow mode: code-impl review dimension table item by item)]]
+
+    **5B. Linkage check**:
+    [[SUBAGENT: archi-feature-relations|mode: check, context: Semantically compare this implementation with featureRelations sources]][[NO-SKILL: (Skill not installed: read `[[__DOCS_DIR__]]/skills/archi-feature-relations/SKILL.md`, follow mode: check logic)]]
+
+    **5C. Data governance sync**:
+    [[SUBAGENT: archi-data-sync|context: Scan this implementation for new business entities/error codes/Schema; incremental sync per 03_data_governance.md rules]][[NO-SKILL: (Skill not installed: read `[[__DOCS_DIR__]]/skills/archi-data-sync/SKILL.md`, follow its execution protocol)]]
+
+    [[INCLUDE: shared/verify-result-handling.md]]
+</step_5_verify>
 
 <step_6_signoff>
     **Terminal Gate** (Do not skip; must complete before output summary):

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

@@ -37,7 +37,7 @@
        - Add Gherkin Scenarios (covering normal flows + exception paths)
        - Add interface/type definitions (if this task is upstream of others)
     5. Update `Spec-Status: Stub → Full`.
-    6. [?UI] If module has UI → generate or update `ui.md` (scope declaration); if new screens are needed, notify user to run the `archi-ui-wireframe` Skill (Skill syncs both `ui_concept.html` + `ui_context.md`).
+    6. [?UI] If module has UI → generate or update `ui.md` (scope declaration); if new screens are needed, [[SKILL: archi-ui-wireframe|invoke skill or notify user to run]][[NO-SKILL: (Skill not installed: read `[[__DOCS_DIR__]]/skills/archi-ui-wireframe/SKILL.md` and prompt user to follow the document)]] (Skill syncs both `ui_concept.html` + `ui_context.md`).
     7. Generate `plan.json` (all tasks as done, recording implemented content).
     8. Present enriched spec summary to user.
 
@@ -49,14 +49,14 @@
     **Role**: Requirements Analyst & Designer
     **Action**:
     - Modify spec.md (logic/rule changes) and ui.md (structure/interaction changes) based on `[context]`.
-    - [?UI Modification] Sync `ui_concept.html` + `ui_context.md` via Skill (Skill is the sole writer of both files):
+    - [?UI Modification] [[SKILL: archi-ui-wireframe|Follow the skill protocol to sync `ui_concept.html` + `ui_context.md` (Skill is the sole writer of both files)]][[NO-SKILL: (Skill not installed: read `[[__DOCS_DIR__]]/skills/archi-ui-wireframe/SKILL.md` and follow its protocol)]]:
 
       | Change Type | Criteria | Action |
       |:---|:---|:---|
       | No screen impact | Logic/data only, no visual diff | Update spec.md only; `ui_concept.html` / `ui_context.md` unchanged |
-      | Minor UI tweak | New/modified state, popup, or local area; overall layout unchanged | Call Skill (Modify screens mode) to update both files; output `MODIFIED: S-XX` |
-      | Screen structure change | Layout refactor, new standalone screen, navigation path change | Call Skill (Modify screens mode) to update both files; output `MODIFIED: S-XX`; if Phase 2 coloring is done, re-color only the modified screen |
-      | Task reduction | Screen/region removed entirely | Call Skill (Remove screens mode) to update both files; output `REMOVED: S-XX` |
+      | Minor UI tweak | New/modified state, popup, or local area; overall layout unchanged | Call skill (Modify screens mode) to update both files; output `MODIFIED: S-XX` |
+      | Screen structure change | Layout refactor, new standalone screen, navigation path change | Call skill (Modify screens mode) to update both files; output `MODIFIED: S-XX`; if Phase 2 coloring is done, re-color only the modified screen |
+      | Task reduction | Screen/region removed entirely | Call skill (Remove screens mode) to update both files; output `REMOVED: S-XX` |
 
     - Ask user questions (A/B/C/D options) to confirm details when requirements are vague.
 
@@ -66,19 +66,28 @@
 <step_3_update_plan>
     **Role**: Tech Lead
     **Action**:
-    - Append new phase to `plan.json` phases array: `Phase X: Change Request (<Date>)`.
+    - Append new Phase object to `plan.json` phases array.
     - List specific Tasks (API update, UI tweak, Test update); each must be verifiable.
     - **Status Transition**: If current task status=`done`, reset to `active` after appending the Phase (otherwise `/archi.code` will be rejected by the Status Gate).
 
-    **Terminal Gate** (Do not skip; must complete before step_4 output):
+    **Terminal Gate** (Do not skip; must complete before step_3_5 starts):
     | Step | Command | Pass Condition |
     |:---|:---|:---|
-    | 1 | `npx archi render` | `.md` views generated |
-    | 2 | [if current status=done] `npx archi task <ID> --status active` | Task status reset to active |
+    | 1 | `npx archi task --check` | No ERROR-level issues |
+    | 2 | `npx archi render` | `.md` views generated |
+    | 3 | [if current status=done] `npx archi task <ID> --status active` | Task status reset to active |
 
     **Output**: plan.json with new tasks appended; if status transition was performed, output `MODIFIED: roadmap.json <ID>.status done→active`.
 </step_3_update_plan>
 
+<step_3_5_verify>
+    **Role**: Independent Reviewer
+
+    [[SUBAGENT: archi-silent-audit|mode: plan-docs, context: Review step_2 updated spec.md/ui.md and step_3 appended plan.json new Phase; ensure doc logic is consistent and new Phase tasks are verifiable]][[NO-SKILL: (Skill not installed: read `[[__DOCS_DIR__]]/skills/archi-silent-audit/SKILL.md`, follow mode: plan-docs review dimension table item by item)]]
+
+    [[INCLUDE: shared/verify-result-handling.md]]
+</step_3_5_verify>
+
 <step_4_summary>
     **Action** (Gate must complete in step_3):
     **Output**: Task update summary with Spec/UI/Plan change overview and Next Steps table. Recommend running `/archi.code <ID>`.

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

@@ -1,7 +1,7 @@
 <protocol_inherit>
-  **Trigger**: `/archi.inherit`
+  **Trigger**: `/archi.inherit [brief_path]`
   **Phase**: Legacy Adoption
-  **Goal**: Reverse-engineer an existing codebase to generate the Architext document skeleton, bringing the project under framework governance.
+  **Goal**: Reverse-engineer an existing codebase to generate the Architext document skeleton, bringing the project under framework governance. Optionally provide a Brief to supplement vision/roadmap (for skeleton repos with minimal code).
 
 <meta>
     <style>Analytical, Systematic, Evidence-Based</style>
@@ -15,6 +15,17 @@
     </principles>
 </meta>
 
+<step_0_ingest>
+    **Role**: Intelligence Analyst
+    **Trigger**: Only when user provides `[brief_path]`. Skip if no argument or path invalid.
+    **Action**:
+    1. Parse `[brief_path]`: if path provided → read that file; if not → look for `project-brief.md` (project root), then `[[__DOCS_DIR__]]/project-brief.md`
+    2. If file exists and non-empty: parse Brief sections, extract project identity, core tasks, tech preferences, constraints, supplementary notes (same as start step_0_ingest)
+    3. If file missing or empty: skip this step; subsequent steps use code only as input
+
+    **Output**: Internal Brief summary (not shown to user), proceed to step_0_recon.
+</step_0_ingest>
+
 <step_0_recon>
     **Role**: Intelligence Analyst
     **Action**:
@@ -118,13 +129,23 @@
 
 <step_3_constitution>
     **Role**: Chief Architect
-    **Input**: Step 1 analysis report + Step 2 supplements (if any).
-    **Action**: Generate project document skeleton in one pass.
+    **Input**: Step 0 Brief parse (if any) + Step 1 analysis report + Step 2 supplements (if any).
+    **Action**: Generate project document skeleton in one pass. **When Brief provided**: Brief takes precedence for vision/roadmap/tech_stack; code still used for map, LEG-xx, directory structure. **When no Brief**: Code only as input (original logic).
 
     ### 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.
 
+    **When Brief provided** (Brief content → target file, same as start):
+    | Brief content | Target file |
+    |:---|:---|
+    | Project identity, target users, success metrics, references | `[[__DOCS_DIR__]]/global/vision.md` |
+    | Tech stack, deployment target, third-party libs/services | rule file `02_tech_stack` |
+    | Core task list | `[[__DOCS_DIR__]]/global/roadmap.json` (phase-1/2, call archi-decompose-roadmap) |
+    | Rules/conventions from supplementary notes | rule file `90_custom_rules` |
+    | Style/tone (UI only) | `design_tokens.json` aestheticDirection etc. |
+
+    **Information from Code** (always applies):
     | Information from Code | Target File |
     |:---|:---|
     | README project description, target users, task list | `[[__DOCS_DIR__]]/global/vision.md` |
@@ -137,21 +158,24 @@
     | [?Data] Schema/Migration files | `[[__DOCS_DIR__]]/global/data_snapshot.json` |
 
     ### 3.1 Vision (`[[__DOCS_DIR__]]/global/vision.md`)
-    - Derive from README + project config
-    - Items that cannot be derived: mark `(AI Inferred — user review recommended)`
+    - **With Brief**: Fill from Brief (same as start); code/README as supplement only
+    - **Without Brief**: Derive from README + project config; mark un-inferrable items `(AI Inferred — user review recommended)`
     - Do not retain template placeholders
 
     ### 3.2 Tech Stack (rule file `02_tech_stack`)
-    - Existing dependencies/config → write directly
-    - Visible code conventions (naming, structure) → write to Coding Standards
+    - **With Brief**: Brief-confirmed items → write directly; Brief blank/"recommend" → AI recommends by project features; code deps/config as supplement
+    - **Without Brief**: Existing dependencies/config → write directly; visible code conventions → Coding Standards
     - Must populate complete Section 1-8
 
     ### 3.3 Custom Rules (rule file `90_custom_rules`)
-    - Extract rules from eslint/prettier/editorconfig
-    - Identify team conventions from code patterns (e.g., named export preference, async/await style)
+    - **With Brief**: Merge Brief supplementary notes + code eslint/prettier etc.
+    - **Without Brief**: Extract from eslint/prettier/editorconfig; identify team conventions from code patterns
 
     ### 3.4 Roadmap (`[[__DOCS_DIR__]]/global/roadmap.json`)
 
+    **With Brief**: [[SKILL: archi-decompose-roadmap|Generate phase-1/2 task chain from Brief task list]]; code functional modules → phase-0 LEG-xx (status=done). Merge both.
+    **Without Brief**: Code functional modules only → phase-0 LEG-xx; phase-1/2 remain empty skeletons.
+
     **Structure**:
     ```json
     {
@@ -221,25 +245,20 @@
     ### 3.7 Other Global Documents (as needed)
     - `dictionary.json`: Extract domain terminology from code
     - [?UI] `design_tokens.json`: Extract from CSS variables/theme
-    - [?UI] `ui_concept.html` + `ui_context.md`: **Not generated by this command.** After inherit completes, prompt the user to run the `archi-ui-wireframe` Skill to generate the global UI wireframe (Skill generates both files simultaneously).
+    - [?UI] `ui_concept.html` + `ui_context.md`: **Not generated by this command.** After inherit completes, [[SKILL: archi-ui-wireframe|invoke skill or prompt user to run]][[NO-SKILL: (Skill not installed: read `[[__DOCS_DIR__]]/skills/archi-ui-wireframe/SKILL.md` and prompt user to follow the document)]] to generate the global UI wireframe (Skill generates both files simultaneously).
     - [?Data] `data_snapshot.json`: Extract from schema/migration
     - `error_codes.json`: Extract from error definitions in code
 
     **Output**: Write all files, then run `npx archi render`.
 </step_3_constitution>
 
-<step_4_audit>
-    **Role**: Chief Auditor
-    **Checklist**:
-    1.  **Vision Alignment**: Does vision.md match actual code functionality?
-    2.  **Tech Stack Consistency**: Does rule file `02_tech_stack` match package.json/config?
-    3.  **Map Coverage**: Does map.json cover all core directories?
-    4.  **Roadmap Completeness**: Does phase-0 cover all identified functional modules?
-    5.  **Stub Completeness**: Does every LEG-xx have a corresponding tasks/ directory and spec.md?
-    6.  **Dictionary Consistency**: No ambiguous or duplicate terms?
-
-    Silently fix issues; mark severe problems as `Risk Warning`.
-</step_4_audit>
+<step_4_verify>
+    **Role**: Independent Reviewer
+
+    [[SUBAGENT: archi-silent-audit|mode: init, context: Review step_3 generated global files (vision, tech_stack, roadmap, map, dictionary, stub specs, 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_5_signoff>
     **Terminal Gate** (Do not skip; must complete before output summary):