architext 0.0.4 → 0.0.6

package/dist/templates/en/briefs/_base.md

@@ -6,7 +6,7 @@
 
 ## Project Overview
 
-**Project Name**: 
+**Project Name**:
 **One-line description**: [What the project is, who it serves, what problem it solves]
 **Problem statement**: [Core pain points for target users? Where do existing solutions fall short?]
 
@@ -18,14 +18,29 @@
 
 ---
 
-## Core Tasks
+## Functional Requirements
 
-> MVP must-have tasks (recommend 3–7), each in one sentence describing expected behavior.
-> Detailed specs are defined in `/archi.plan`; here just clarify "what to build."
+> Core capabilities to implement—describe "what" not "how."
+> AI will decompose these into implementation tasks; here just clarify the business goal.
 
-1. 
-2. 
-3. 
+-
+-
+-
+
+---
+
+## Business Process
+
+> If your project has clear user journeys or core workflows, describe them here.
+> No need for diagrams—describe steps in text; AI will infer system behavior from this.
+> Leave blank if not applicable; AI will derive from core tasks.
+
+<!-- Format reference:
+### [Process name]
+1. User [action] → System [response]
+2. User [action] → System [response]
+3. ...
+-->
 
 ---
 
@@ -36,7 +51,7 @@
 >
 > Format:
 > - **[Task/page name]**: Describe behavior, flow, constraints
-> - May include screenshot/sketch links
+> - May include screenshot/sketch (see "Design Assets" below)
 
 ---
 
@@ -45,7 +60,7 @@
 > Fill in what's confirmed. Leave blank or write "recommend" for the rest; AI will recommend based on project characteristics.
 
 **Project type**: [[__PROJECT_TYPE__]]
-<!-- Auto-filled by archi init; if writing manually, refer to the project type table in the archi-decompose-roadmap SKILL -->
+<!-- Auto-filled by archi init; if writing manually, choose from ui/data/api/cli/lib/mobile/desktop/miniapp/extension/realtime/ai -->
 **Language/runtime**: [e.g.: TypeScript + Node.js 22]
 **Core framework**: [e.g.: Next.js 15 / Fastify / Tauri]
 **Package manager**: [e.g.: pnpm / npm / yarn / cargo]
@@ -69,6 +84,13 @@
 **Directory structure**: [already defined → describe key dirs / none (AI generates based on pattern)]
 **Branching strategy**: [e.g.: Trunk-based / Git Flow / GitHub Flow]
 **Commit convention**: [e.g.: Conventional Commits (feat/fix/chore) / custom → describe]
+
+**AI Git Workflow** (Git conventions when AI runs `/archi.code`):
+- **Auto commit**: [Yes - auto git commit after each Task / No - generate commit message only, user commits manually]
+- **Commit granularity**: [Per Task / Per Phase / As needed]
+- **Branching**: [Work directly on main / Create branch per Task `feat/{task-id}`]
+- **Auto push**: [Yes / No]
+
 **Testing preference**: [e.g.: Vitest / Jest / pytest / no special requirements]
 
 ---
@@ -78,14 +100,33 @@
 > What already exists that AI should know—to avoid reinventing or making conflicting decisions.
 
 **Project starting point**: [Greenfield / based on existing repo (brief status and tech debt)]
-**Design assets**: [Figma link / design mockup screenshots / none (AI designs)]
-**Brand guidelines**: [Existing logo/colors/fonts → describe or link / none]
 **Existing API/backend**: [API docs link / brief available endpoints / none (build from scratch)]
 **Third-party services**: [Confirmed services, e.g.: Auth0, Stripe, AWS S3, Resend...]
 **Existing data**: [Existing DB/data sources? Format? Migration needed? / none]
 
 ---
 
+## Design Assets
+
+> Provide visual/design input for AI—directly impacts UI and architecture decision quality.
+> Two ways to provide files:
+> 1. **Local files**: Place files in `brief-assets/` directory, reference by format below
+> 2. **External links**: Paste URL directly
+>
+> Reference format: `- [semantic label] ./brief-assets/filename`
+>
+> Format reference:
+> - [Competitor reference - home] ./brief-assets/linear-dashboard.png
+> - [My sketch] ./brief-assets/sketch-v1.png
+> - [Brand palette] ./brief-assets/brand-colors.pdf
+> - [API docs] ./brief-assets/api-spec.yaml
+> - [Database Schema] ./brief-assets/schema.sql
+
+**Design mockups/screenshots**: [Reference local files per format above / Figma link / none (AI designs)]
+**Brand guidelines**: [Existing logo/colors/fonts → reference file or describe / none]
+
+---
+
 <!-- @slot:style -->
 
 ## Scope & Constraints
@@ -94,7 +135,6 @@
 - [e.g.: No i18n this release / no mobile adaption / no paid features]
 
 **Hard constraints**:
-- **Timeline**: [e.g.: 4-week MVP / no hard deadline]
 - **Compatibility**: [e.g.: Chrome 90+ / Node 18+ / iOS 15+]
 - **Performance**: [e.g.: First paint < 2s / API P99 < 500ms / no special requirements]
 - **Compliance/accessibility**: [e.g.: WCAG 2.1 AA / GDPR / none]
@@ -112,4 +152,4 @@
 
 ## Additional Notes
 
-> Anything not covered above: background story, special requirements, rationale for decisions, team tech preferences, etc.
+> Anything not covered above: background story, special requirements, rationale for decisions, etc.

package/dist/templates/en/briefs/_modules.md

@@ -5,10 +5,37 @@
 <!-- @tech:data -->
 **Database**: [e.g.: PostgreSQL / MongoDB / SQLite]
 **ORM / Query Builder**: [e.g.: Prisma / Drizzle / TypeORM]
+
+### Data Model Draft
+
+> If you already know core data entities and relationships, describe them here. No need for full schema—list entity names and key fields.
+> AI will generate detailed data model in `/archi.plan`; here just clarify "what data exists."
+> Leave blank if not applicable; AI will derive from core features.
+
+<!-- Format reference:
+- **User**: email, name, role (admin/user), avatar
+- **Post**: title, content, status (draft/published), author → User
+- **Comment**: body, author → User, post → Post
+- User 1:N Post, Post 1:N Comment
+-->
+
 <!-- @end -->
 
 <!-- @tech:api -->
 **API style**: [e.g.: RESTful / GraphQL / gRPC / tRPC]
+
+### Existing API Endpoints
+
+> If you have existing backend API (self-hosted or third-party), list core endpoints here. Or place full docs in `brief-assets/`.
+> Leave blank if not applicable.
+
+<!-- Format reference:
+- `POST /auth/login` → returns JWT token
+- `GET /users/:id` → user detail
+- `POST /posts` → create post (auth required)
+- Full docs: [API docs] ./brief-assets/api-spec.yaml
+-->
+
 <!-- @end -->
 
 <!-- @tech:cli -->
@@ -44,8 +71,8 @@
 
 ### Visual Reference
 
-> Provides aesthetic input for AI — directly impacts `ui_concept.html` quality.
-> Fill in any of the fields below; the more you provide, the closer AI can match your vision.
+> Provides aesthetic input for AI—directly impacts visual quality of screen prototypes in the `screens/` directory.
+> Any field below is valid; the more you fill, the better AI can match your expected style.
 
 **Competitor/inspiration screenshots**: [paste image / Figma link / URL]
 **Brand palette**: [primary color Hex / gradient description / none (AI generates from aesthetic direction)]
@@ -116,7 +143,7 @@
 **Real-time transport**: [e.g.: Socket.io / native WebSocket / SSE / WebRTC]
 **Real-time framework/hosting**: [e.g.: Ably / Pusher / Liveblocks / self-hosted]
 **Room/channel model**: [e.g.: subscribe by user ID / room by document ID / broadcast]
-**[?CRDT] Conflict resolution**: [e.g.: Yjs / Automerge / not needed (broadcast only)]
+**(CRDT projects only) Conflict resolution**: [e.g.: Yjs / Automerge / not needed (broadcast only)]
 **Offline support**: [e.g.: offline queue + reconnect sync / not needed]
 <!-- @end -->
 
@@ -125,7 +152,7 @@
 **AI framework**: [e.g.: Vercel AI SDK / LangChain / LlamaIndex / direct API calls]
 **Tool/Function Calling**: [e.g.: needed (list tool names) / not needed]
 **Memory approach**: [e.g.: vector DB (pgvector/Pinecone) / sliding window history / none]
-**[?MCP] MCP protocol**: [e.g.: @modelcontextprotocol/sdk / not needed]
+**(MCP projects only) MCP protocol**: [e.g.: @modelcontextprotocol/sdk / not needed]
 **Streaming output**: [e.g.: SSE streaming / batch response]
 <!-- @end -->
 

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

@@ -0,0 +1,40 @@
+{
+  "errorPatterns": {
+    "_comment": "Error patterns: { id: unique identifier, watchFor: [scenarios to watch before execution], matchWhen: [keywords to match after error], cause: root cause, solution: solution, lesson: lesson/principle }. AI appends here after resolving errors",
+    "examples": [
+      {
+        "id": "build-vite-config-missing",
+        "watchFor": ["Run npm run build", "Modify vite.config.ts"],
+        "matchWhen": ["ENOENT", "vite.config", "Cannot find module"],
+        "cause": "Config file deleted or node_modules not installed",
+        "solution": "Check file existence, run npm install to reinstall deps",
+        "lesson": "Backup before modifying configs, regularly verify node_modules integrity"
+      },
+      {
+        "id": "type-import-assertion-deprecated",
+        "watchFor": ["Import JSON files"],
+        "matchWhen": ["assert", "SyntaxError", "import", "type"],
+        "cause": "Node.js 18+ deprecated import assert syntax, use import attributes instead",
+        "solution": "Change assert { type: 'json' } to with { type: 'json' }",
+        "lesson": "Watch Node.js version updates, verify import JSON syntax for your version"
+      }
+    ]
+  },
+  "checkpoints": {
+    "_comment": "Checkpoints: { before: operation description to match before execution, check: [list of errorPatterns.id to check] }. AI auto-generates from watchFor scenarios",
+    "examples": [
+      {
+        "before": "Run npm run build",
+        "check": ["build-vite-config-missing"]
+      },
+      {
+        "before": "Modify config files",
+        "check": ["build-vite-config-missing"]
+      },
+      {
+        "before": "Import JSON files",
+        "check": ["type-import-assertion-deprecated"]
+      }
+    ]
+  }
+}

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

@@ -1,99 +1,55 @@
 {
-  "governance": {
-    "coreRules": [
+  "directoryMapping": {
+    "_comment": "Code directory ↔ module mapping: { path: directory path, module: module name, responsibility: responsibility description }",
+    "examples": [
       {
-        "file": "00_system.md",
-        "role": "System Role",
-        "when": "At the start of every session (Identity, Core Principles)"
+        "path": "src/features/auth",
+        "module": "auth",
+        "responsibility": "User authentication, login, registration"
       },
       {
-        "file": "01_workflow.md",
-        "role": "SOP",
-        "when": "Decides current task flow (Task vs Fix) & Acceptance Criteria"
-      },
-      {
-        "file": "02_tech_stack.md",
-        "role": "Tech Stack",
-        "when": "Tech choices, coding standards, engineering governance"
-      },
-      {
-        "file": "03_data_governance.md",
-        "role": "Data Governance",
-        "when": "When reading/writing global JSON data files"
-      },
-      {
-        "file": "04_cli_tools.md",
-        "role": "CLI Reference",
-        "when": "When executing Terminal Gate commands (npx archi task/plan/render syntax reference)"
-      },
-      {
-        "file": "99_context_glue.md",
-        "role": "Context Bridge",
-        "when": "Automatically links context docs when touching code"
+        "path": "src/features/todos",
+        "module": "todo",
+        "responsibility": "Todo CRUD operations"
       }
-    ],
-    "globalReference": [
-      {
-        "file": "roadmap.json",
-        "role": "Roadmap",
-        "content": "Progress tracking, milestones, technical debt management"
-      },
-      {
-        "file": "vision.md",
-        "role": "Vision",
-        "content": "Vision, North Star Metric, Design Philosophy"
-      },
-      {
-        "file": "map.json",
-        "role": "Map (This file)",
-        "content": "Directory structure, file index, logical topology"
-      },
-      {
-        "file": "dictionary.json",
-        "role": "Dictionary",
-        "content": "Business glossary, shared component registry"
-      },
-      {
-        "file": "design_tokens.json",
-        "role": "Visuals [?UI]",
-        "content": "Colors, typography, spacing variables"
-      },
-      {
-        "file": "data_snapshot.json",
-        "role": "Data [?Data]",
-        "content": "Database Schema snapshot"
-      },
-      {
-        "file": "error_codes.json",
-        "role": "Errors",
-        "content": "Error codes & protocol contracts"
+    ]
+  },
+  "logicalTopology": {
+    "_comment": "Logical topology: { module: module name, layer: layer(layer/domain/interface/infrastructure), depends: [dependent modules] }",
+    "examples": [
+      { "module": "auth", "layer": "domain", "depends": ["user-repo"] },
+      { "module": "todo", "layer": "domain", "depends": ["auth", "todo-repo"] }
+    ]
+  },
+  "criticalUserJourneys": {
+    "_comment": "Critical user journeys: { journey: journey name, steps: [steps], owner: owning task ID }",
+    "examples": [
+      {
+        "journey": "User Registration & Login",
+        "steps": [
+          "Visit homepage",
+          "Click register",
+          "Fill form",
+          "Submit",
+          "Login success"
+        ],
+        "owner": "FEAT-AUTH"
       }
     ]
   },
-  "featureDocs": [
-    {
-      "file": "spec.md",
-      "category": "Specification",
-      "purpose": "Business Logic, Algorithms, Acceptance Criteria (Logic)"
-    },
-    {
-      "file": "ui.md",
-      "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",
-      "purpose": "Detailed Step Breakdown & Test Cases (Execution)"
-    }
-  ],
-  "directoryMapping": [],
-  "logicalTopology": [],
-  "criticalUserJourneys": [],
-  "featureRelations": []
+  "featureRelations": {
+    "_comment": "Impact relations organized as networks: { group: network name, members: [member files], rule: change rule }",
+    "examples": [
+      {
+        "group": "Tech Specs",
+        "members": [
+          "tech_stack.md",
+          "prompts/code.md",
+          "prompts/audit.md",
+          "rules/00_system.md"
+        ],
+        "rule": "Tech stack changes need to sync protocol docs"
+      }
+    ]
+  }
 }

package/dist/templates/en/{rules/04_cli_tools.md → docs/global/references/cli_reference.md}

@@ -1,13 +1,6 @@
----
-description: CLI Reference Manual. Working directory rule and command syntax for npx archi task/plan/render.
-globs: **/*
-applyTo: **/*
-alwaysApply: true
----
-
 # CLI Reference
 
-> **Role**: Command quick-reference. Provides syntax and parameters for `npx archi` commands, for use during Terminal Gate execution.
+> **Role**: Command reference manual. Provides syntax and parameters for `npx archi` commands, for use during Terminal Gate execution.
 
 ## ⛔ Working Directory Gate
 
@@ -16,7 +9,7 @@ alwaysApply: true
 | Check | Pass Condition |
 |:---|:---|
 | Current directory | Must be project root (directory containing `[[__DOCS_DIR__]]/`) |
-| If unsure | Confirm current directory first; forbidden to guess |
+| When uncertain | Confirm current directory first; do not guess |
 | In subdirectory | Must `cd` to root before executing |
 
 ---
@@ -27,7 +20,7 @@ alwaysApply: true
 
 | Subcommand | Purpose | Example |
 |:---|:---|:---|
-| `npx archi task` | List all tasks with progress | `npx archi task` |
+| `npx archi task` | List all tasks and progress | `npx archi task` |
 | `npx archi task <ID> --status <s>` | Update task status | `npx archi task INF-001 --status done` |
 | `npx archi task --check` | Check Roadmap consistency | `npx archi task --check` |
 
@@ -37,7 +30,7 @@ alwaysApply: true
 
 | Subcommand | Purpose | Example |
 |:---|:---|:---|
-| `npx archi plan <ID>` | Check Task's Plan completion | `npx archi plan SUB-01` |
+| `npx archi plan <ID>` | Check Task Plan completion | `npx archi plan SUB-01` |
 
 Automatically identifies Manual Verification sections and excludes them from automated statistics.
 
@@ -45,6 +38,6 @@ Automatically identifies Manual Verification sections and excludes them from aut
 
 | Subcommand | Purpose | Example |
 |:---|:---|:---|
-| `npx archi render` | Render all JSON data files into human-readable `.md` views | `npx archi render` |
+| `npx archi render` | Render all JSON data files as human-readable `.md` views | `npx archi render` |
 
-> `.md` views are auto-generated; forbidden to edit directly. Modifications must go through `.json` source files.
+> `.md` views are auto-generated; do not edit directly. Modifications must go through the `.json` source files.

package/dist/templates/en/{rules/02_tech_stack.md → docs/global/tech_stack.md}

@@ -1,10 +1,3 @@
----
-description: Technical Standards & Technology Stack. Contains language versions, framework choices, coding conventions, naming rules, and forbidden patterns. Consult when writing code.
-globs: **/*
-applyTo: **/*
-alwaysApply: true
----
-
 # Tech Stack & Engineering Standards: [Project Name]
 
 > **Role:** The "Law" of the codebase. Defines tools, structure, and engineering workflows.
@@ -53,23 +46,19 @@ alwaysApply: true
 
 ---
 
-## 4. UI Protocol: ITP v3.0 (Dual-Artifact) [Optional - Only for UI Projects]
+## 4. UI Protocol: ITP v3.0 (Tri-Artifact) [Optional - Only for UI Projects]
 <!-- Core UI Description Protocol -->
 > **Note:** If project has no UI (e.g. CLI, Backend API, Library), remove this section.
 
-### 4.1 Dual-Artifact Strategy
-
-UI artifact hierarchy:
+### 4.1 Tri-Artifact Strategy
 
 | Artifact | Format | Reader | Responsibility |
 |:---|:---|:---|:---|
-| `ui_concept.html` | Single-file HTML | Human (browser) | **Global visual source of truth** — wireframes/styled screens for the entire project |
-| `ui_context.md` | Structured Markdown | AI (plan/code/audit/edit) | **AI screen index** — lightweight list of screen IDs / routes / states / navigation graph / shared components |
-| `ui.md` | ITP v3.0 DSL | AI (code/audit) | Task-level UI scope declaration — which screens/components this task covers |
-- `ui_concept.html` is generated by the `archi-ui-wireframe` Skill, covering all user-visible screens; for human browser preview only
-- `ui_context.md` is generated by the same Skill simultaneously; it is the sole AI entry point for UI structure; do not edit manually
-- `ui.md` only declares "which screens/states in ui_context.md this task is responsible for"; do not redefine global layout
-- Code phase uses `ui.md` (task design) + `ui_context.md` (structure/navigation) + `design_tokens.json` (visual constraints) as source; also uses `ui_concept.html` as **read-only visual reference** to calibrate layout; implement equivalent visual effect with the **project's own tech stack**
+| `screens/` | Multi-file HTML (`index.html` + `S-XX.html` + `_shared.css`) | Human (browser) | **Global visual source of truth** — triggered by `/archi.ui` Skill; each screen independently previewable |
+| `ui_context.md` | Structured Markdown | AI (plan/code/audit/edit) | **AI screen index** — sole AI entry point for UI structure; generated by same Skill; do not edit manually |
+| `ui.md` | ITP v3.0 DSL | AI (code/audit) | Task-level UI scope declaration — only declares which screens/states this task covers; do not redefine global layout |
+
+- Code phase uses `ui.md` + `ui_context.md` + `design_tokens.json` as source; `screens/S-XX.html` as **read-only visual reference**; implement equivalent visual effect with **project's own tech stack**
 
 ### 4.2 Naming (PrefixFunction)
 Component naming must follow `Prefix+Function` format:

package/dist/templates/en/docs/global/vision.md

@@ -77,6 +77,6 @@ description: Project Constitution: Vision, Personas, Principles & Boundaries.
 **Trigger**: Only modify during project initialization (`/archi.start`) or major strategic pivot (`/archi.revise`).
 
 **Action**:
-1.  **Alignment**: Ensure Section 3 (Principles) conflicts with technology choices in `02_tech_stack.md`.
+1.  **Alignment**: Ensure Section 3 (Principles) conflicts with technology choices in `tech_stack.md`.
 2.  **Completeness**: Must fill all `[ ]` placeholders, strictly no "Example" text remaining.
 3.  **Consistency**: All Task Specs (`.spec.md`) must reference the Vision in this file to ensure alignment.