architext 0.0.3 → 0.0.5

package/CHANGELOG.md

@@ -6,7 +6,62 @@ All notable changes are documented here, following [Keep a Changelog](https://ke
 
 ---
 
-## [Unreleased](https://github.com/JiuNian3219/architext/compare/v0.0.3...HEAD) / 待发布
+## [Unreleased](https://github.com/JiuNian3219/architext/compare/v0.0.5...HEAD) / 待发布
+
+---
+
+## [0.0.5](https://github.com/JiuNian3219/architext/releases/tag/v0.0.5) - 2026-03-06
+
+### Added / 新增
+
+- `FileModel` 注册表，实现声明式文件管理，替代分散的路径硬编码 / Introduced FileModel registry for declarative file management
+- `archi init` 支持 `--yes` 和 `--brief` flag，实现非交互式初始化 / Added `--yes` and `--brief` flags for non-interactive init
+- Brief 附件资产目录支持（`_modules.md` 等附件模块）/ Added Brief attachment asset directory support
+- Skill 类型声明（`type: specialist` / `type: reviewer`）/ Added Skill type classification in frontmatter
+
+### Changed / 变更
+
+- 重构 `init`、`uninstall`、`update` 命令，基于 FileModel 驱动，逻辑更一致 / Refactored commands to be driven by FileModel
+- 拆分 `scaffold.ts` 为 `brief.ts` 和 `ide-integrations.ts`，拆分 `index.ts` 为 `collector.ts` 和 `serializer.ts` / Decomposed large source files for clarity
+- 精简 14 个中文协议文件，总行数从 2474 压缩至 1852（-25%）/ Compressed 14 zh protocol files by 25%
+- `01_workflow.md` 改造为 Chat Mode：高频命令（plan/code/edit/fix/scope）支持自然语言触发，AI 自动加载协议执行 / Workflow now supports natural-language intent detection for high-frequency commands
+- 两阶段协议生成合并为统一协议，减少用户操作步骤 / Merged two-phase protocol generation into single flow
+- 更新触发器描述，支持自然语言触发 / Updated trigger descriptions to support natural language
+- 补充 `01_workflow` 中 `ref` 与 `recover` 命令路由 / Added routing for `ref` and `recover` commands
+
+### Fixed / 修复
+
+- 修正 `inherit` 协议表述，避免误导用户认为会覆盖既有 `.architext` 数据 / Fixed `inherit` wording to prevent misunderstanding about overwriting existing data
+- 补全 zh prompts 到 en 的完整翻译 / Completed full translation of zh prompts to en
+
+---
+
+## [0.0.4](https://github.com/JiuNian3219/architext/releases/tag/v0.0.4) - 2026-03-01
+
+### Added / 新增
+
+- `archi pack` + `/archi.recover` — 用户数据备份与恢复流程 / User data backup and restore flow
+- `/archi.ref` — 外部知识引用管理命令 / External knowledge reference management command
+- `design.md` 技术方案设计模板与 `archi-design-patterns` Skill / Design template and archi-design-patterns Skill
+- 项目初始化流程支持可选生成 `project-brief.md` / Init flow supports optional `project-brief.md` generation
+- 子代理审查层与内容切片机制 / Sub-agent review layer and content slicing mechanism
+- 维度积木 spec 骨架、WBS 分解与任务类型体系 / Spec skeleton, WBS decomposition and task type system
+- OpenCode、Claude Code 作为目标 IDE 支持 / OpenCode and Claude Code as target IDE options
+- 网站 Iterate 区块，Workflow 简化为 start → plan → code → audit 四阶段 / Website Iterate section, simplified Workflow to four stages
+
+### Changed / 变更
+
+- 移除 zh-Hant 支持，简化为 zh + en 双语 / Removed zh-Hant, simplified to zh + en
+- 项目类型重构为特征标签体系 / Project type refactored to feature tag system
+- 移除 terminal-gate-base、status-gate 共享片段，内联至各协议 / Inlined shared gate snippets into protocols
+
+### Fixed / 修复
+
+- 更新 prompts 时解析 `[[SKILL:...]]` / `[[NO-SKILL:...]]` 能力标记 / Parse capability refs when updating prompts
+- 统一 templates 中 Skill 调用格式 / Unified Skill invocation format in templates
+- 在 `02_tech_stack` 中为 ITP 固定协议添加分区标记 / Added section markers for ITP fixed protocols
+- 明确协议可覆盖 `00_system` 的范围 / Clarified protocol override scope for `00_system`
+- 在 `00_system` 中定义跨文件规则优先级链 / Defined cross-file rule priority chain
 
 ---
 

package/README.md

@@ -10,7 +10,7 @@
 [![License: MIT](https://img.shields.io/badge/license-MIT-green)](LICENSE)
 [![Node.js](https://img.shields.io/badge/node-%3E%3D18-brightgreen)](https://nodejs.org)
 
-**Supported IDEs:** Cursor *(recommended)* · Windsurf · Trae · VS Code
+**Supported IDEs:** Cursor *(recommended)* · Windsurf · Trae · VS Code · Claude Code · OpenCode
 
 </div>
 
@@ -28,6 +28,8 @@ Before a single line of code is written, Architext forces you and your AI to ali
 
 > **No Docs, No Code.** Code is just a downstream artifact of documents.
 
+Architext targets **small-to-medium applications**, designed for **solo developers** or **solo + AI assistant** workflows. Whether you use chat-based AI today or a future JARVIS-like persistent assistant, the document-driven approach gives AI stable context, clear execution boundaries, and keeps you in control of every decision.
+
 Architext operates in two layers:
 
 | Layer | How to trigger | Responsibility |
@@ -64,8 +66,9 @@ npx archi init
 
 ```
 ✔ Select language    › English
-✔ Select IDE(s)      › Cursor   (multiselect — Cursor / Windsurf / Trae / VS Code)
+✔ Select IDE(s)      › Cursor   (multiselect — Cursor / Windsurf / Trae / VS Code / Claude Code / OpenCode)
 ✔ Select project type › Web SPA / PWA
+✔ Generate project-brief.md? › Yes (fill in project requirements for /archi.start or /archi.inherit)
 
 ● Deploying Architext...
 ✔ Docs deployed      → .architext/
@@ -84,7 +87,7 @@ npx archi init
 
 **Step 2 — AI chat: initialize your project**
 
-`archi init` generates a tailored `project-brief.md` at your project root. Fill it in, then run:
+When you choose to generate it, `archi init` creates a tailored `project-brief.md` at your project root. Fill it in, then run:
 
 ```
 /archi.start project-brief.md
@@ -92,7 +95,7 @@ npx archi init
 
 The AI reads the brief, interviews you on key decisions, and generates the project's foundation documents (`vision.md`, `roadmap.json`, `tech_stack`, etc.).
 
-> **Existing codebase?** Skip `/archi.start` and use `/archi.inherit` instead — it reverse-engineers your project and registers existing features as `LEG-xx` tasks.
+> **Existing codebase?** Skip `/archi.start` and use `/archi.inherit` instead — it reverse-engineers your project and registers existing features as `LEG-xx` tasks. Optional: pass `project-brief.md` when the codebase is minimal (skeleton repo) to supplement vision and roadmap.
 
 ---
 
@@ -101,9 +104,10 @@ The AI reads the brief, interviews you on key decisions, and generates the proje
 The main trunk of a project lifecycle. Everything happens in your AI chat window.
 
 ```
-project-brief.md → /archi.start → [/archi.scope] → /archi.plan → /archi.code → /archi.audit
+project-brief.md → /archi.start → /archi.plan → /archi.code → /archi.audit
                                          ↑
-                               use when you have extra requirements to decompose
+                    /archi.scope runs anytime you have NEW feature requirements
+                    (not limited to "right after start" — mid-project, post-release, etc.)
 ```
 
 **Stage 1 — Initialize**
@@ -123,14 +127,15 @@ AI:   [Analyzing project brief...]
       ✔ MODIFIED: .cursor/rules/02_tech_stack.mdc    (filled with project tech decisions)
       ✔ MODIFIED: .cursor/rules/90_custom_rules.mdc  (filled with team conventions)
 
-      Next: run /archi.scope to decompose requirements into tasks.
+      Next: if the brief covers everything → /archi.plan <first-task-id>
+            if you have more requirements → /archi.scope to add tasks first
 ```
 
 > **Existing codebase?** Use `/archi.inherit` instead — it reverse-engineers your project and registers existing features as `LEG-xx` tasks. Also generates `map.json`.
 
-**Stage 2 — Decompose (optional)**
+**Stage 2 — Decompose (optional, runs anytime)**
 
-> Use `/archi.scope` when you have requirements beyond what's in the initial brief. If the brief already covers everything, go straight to Stage 3.
+> `/archi.scope` is **not** "the step after start." Run it **whenever** you have new feature requirements beyond what's in the initial brief or current roadmap — right after start, mid-project, or after all tasks are done.
 
 ```
 You:  /archi.scope scope-brief.md           ← provide a file, or run bare to trigger an interview
@@ -204,7 +209,80 @@ AI:   [Reading code + spec + plan + vision + tech_stack...]
       [LOW]    Token expiry not configurable via env var → suggest /archi.edit
 ```
 
-> **Daily development between commands** is driven by natural language Chat Mode — ask questions, tweak code, debug — no slash commands needed. Four of the seven rule files act as always-on base rules: `00_system`, `02_tech_stack`, `90_custom_rules`, `99_context_glue`.
+> **Daily development between commands** is driven by natural language **Chat Mode**. Describe what you want in plain language — e.g. "add a login feature" or "fix the auth bug" — and the AI will automatically load and execute the right protocol (scope/plan/code/edit/fix). No need to manually type `/archi.*` slash commands. For questions, trivial edits, and debugging, the AI answers directly. Four of the seven rule files act as always-on base rules: `00_system`, `02_tech_stack`, `90_custom_rules`, `99_context_glue`.
+
+---
+
+## Tutorials
+
+Different scenarios, same protocol. Pick the one that matches your situation.
+
+### Tutorial A: New project, brief covers everything
+
+Your `project-brief.md` already lists all features. No scope needed.
+
+```
+/archi.start project-brief.md  →  /archi.plan FEAT-001  →  /archi.code FEAT-001  →  ...
+```
+
+Start produces a roadmap. Go straight to plan the first task, then code.
+
+---
+
+### Tutorial B: New project, brief incomplete
+
+You ran start, but later realize you forgot features or want to add more.
+
+```
+/archi.start project-brief.md  →  /archi.scope scope-brief.md  →  /archi.plan FEAT-001  →  ...
+```
+
+Scope appends new tasks to `roadmap.json`. Then plan and code as usual.
+
+---
+
+### Tutorial C: Add features mid-project
+
+You're already building. FEAT-001 is done, and you want to add FEAT-002, FEAT-003, etc.
+
+```
+...  →  /archi.scope scope-brief.md  →  /archi.plan FEAT-002  →  /archi.code FEAT-002  →  ...
+```
+
+**Scope runs anytime** — not only after start. Whenever you have new requirements beyond the current roadmap, run scope.
+
+---
+
+### Tutorial D: Existing codebase
+
+You have an existing repo. Adopt Architext without rewriting.
+
+```
+npx archi init  →  /archi.inherit [project-brief.md]  →  /archi.edit LEG-xx 补全 Stub  →  /archi.code LEG-xx
+```
+
+Inherit reverse-engineers the repo and registers features as `LEG-xx` tasks. Use edit to complete stub specs, then code when needed.
+
+---
+
+### Tutorial E: Bug fix
+
+```
+/archi.fix FEAT-001 "login fails when password has special chars"
+```
+
+Fix diagnoses, appends a Bugfix Phase to the plan, and repairs the code.
+
+---
+
+### When to use /archi.scope (summary)
+
+| When | Action |
+|:---|:---|
+| Right after start, brief didn't cover everything | scope |
+| Mid-project, new feature idea | scope |
+| All tasks done, want to add a new module | scope |
+| Brief already covers everything | Skip scope, go to plan |
 
 ---
 
@@ -212,10 +290,12 @@ AI:   [Reading code + spec + plan + vision + tech_stack...]
 
 ### AI Chat Commands
 
+You can trigger these either by typing `/archi.<command>` or by describing your intent in natural language — Chat Mode will automatically load and execute the matching protocol.
+
 | Command | Description |
 |:---|:---|
 | `/archi.start [brief]` | Read a project brief and generate foundation docs (vision / roadmap / tech_stack etc.) |
-| `/archi.inherit` | Reverse-engineer an existing codebase; register features as `LEG-xx` tasks |
+| `/archi.inherit [brief]` | Reverse-engineer existing codebase; optionally pass project-brief.md to supplement vision/roadmap (skeleton repos) |
 | `/archi.scope [file_path]` | Decompose extra requirements into roadmap tasks; omit file to trigger an interview |
 | `/archi.plan <ID> [context]` | Deep architecture interview → spec / plan ([?UI] also ui.md + ui_concept.html); supply context to reduce questions |
 | `/archi.code <ID>` | Implement from plan phase by phase; only `active` tasks are allowed |
@@ -278,7 +358,7 @@ Agent mode is great for single sessions. Architext provides persistent context t
 
 **Q: Can I use this on an existing codebase?**
 
-Yes. Run `/archi.inherit` — Architext analyzes your existing code and generates a document skeleton. Existing features are registered as `LEG-xx` tasks with stub specs, so you can gradually adopt the workflow without a big-bang rewrite.
+Yes. Run `npx archi init` first to deploy the framework, then run `/archi.inherit` — Architext analyzes your existing code and fills the document skeleton (does not overwrite your existing content). Existing features are registered as `LEG-xx` tasks with stub specs, so you can gradually adopt the workflow without a big-bang rewrite.
 
 > **Note**: `/archi.inherit` is still early-stage. Analysis results for large or complex repos may be incomplete and require manual cleanup. Feel free to open an Issue if you hit problems.
 
@@ -294,6 +374,8 @@ Four IDEs are currently supported. During `archi init` you manually select which
 | Windsurf | `.windsurf/rules/` | `.md` | Supported |
 | Trae | `.trae/rules/` | `.md` | Supported |
 | VS Code | `.github/instructions/` | `.instructions.md` | Supported |
+| Claude Code | `.claude/rules/` | `.md` | Supported |
+| OpenCode | `.opencode/rules/` | `.md` | Supported |
 
 Support for additional editors is planned.
 

package/README.zh-CN.md

@@ -10,7 +10,7 @@
 [![License: MIT](https://img.shields.io/badge/license-MIT-green)](LICENSE)
 [![Node.js](https://img.shields.io/badge/node-%3E%3D18-brightgreen)](https://nodejs.org)
 
-**支持的 IDE：** Cursor *(推荐)* · Windsurf · Trae · VS Code
+**支持的 IDE：** Cursor *(推荐)* · Windsurf · Trae · VS Code · Claude Code · OpenCode
 
 </div>
 
@@ -28,6 +28,8 @@ Architext 是一套**文档驱动 AI 开发 (DDAD)** 协议，将你的 AI 编
 
 > **无文档，不代码。** 代码只是文档的下游产物。
 
+Architext 面向**中小型应用**，为 **1 人团队** 或 **1 人 + AI 助手** 的协作模式设计。无论你用的是对话式 AI 还是未来的「贾维斯式」持续助手，文档驱动的工作流都能让 AI 有稳定的上下文、清晰的执行边界，而你始终掌握决策权。
+
 Architext 以两个层次协同运作：
 
 | 层次 | 触发方式 | 职责 |
@@ -64,8 +66,9 @@ npx archi init
 
 ```
 ✔ 选择语言      › 简体中文
-✔ 选择 IDE      › Cursor   (多选 — Cursor / Windsurf / Trae / VS Code)
+✔ 选择 IDE      › Cursor   (多选 — Cursor / Windsurf / Trae / VS Code / Claude Code / OpenCode)
 ✔ 选择项目类型  › Web SPA / PWA
+✔ 是否生成 project-brief.md？ › 是（生成后填写项目需求，供 /archi.start 或 /archi.inherit 使用）
 
 ● 正在部署 Architext...
 ✔ 文档已部署       → .architext/
@@ -84,7 +87,7 @@ npx archi init
 
 **第二步 · AI 对话：初始化项目**
 
-`archi init` 会在项目根目录自动生成一份 `project-brief.md`。填写完毕后，在 AI 编辑器中运行：
+选择生成时，`archi init` 会在项目根目录生成 `project-brief.md`。填写完毕后，在 AI 编辑器中运行：
 
 ```
 /archi.start project-brief.md
@@ -92,7 +95,7 @@ npx archi init
 
 AI 读取 Brief，就关键决策向你提问，生成项目的基础文档（`vision.md`、`roadmap.json`、`tech_stack` 等）。
 
-> **已有代码？** 跳过 `/archi.start`，改用 `/archi.inherit` —— 逆向分析项目，将已有功能注册为 `LEG-xx` 任务，同时生成 `map.json`。
+> **已有代码？** 跳过 `/archi.start`，改用 `/archi.inherit` —— 逆向分析项目，将已有功能注册为 `LEG-xx` 任务，同时生成 `map.json`。可选：代码库尚空时传 `project-brief.md` 补充愿景与路线图。
 
 ---
 
@@ -101,9 +104,10 @@ AI 读取 Brief，就关键决策向你提问，生成项目的基础文档（`v
 项目全生命周期的主干路径，全部在 AI 对话框中完成。
 
 ```
-project-brief.md → /archi.start → [/archi.scope] → /archi.plan → /archi.code → /archi.audit
+project-brief.md → /archi.start → /archi.plan → /archi.code → /archi.audit
                                         ↑
-                              有额外需求时使用，可多次运行
+              /archi.scope  anytime you have NEW feature requirements
+              （不限「start 之后」——项目进行中、发布后均可）
 ```
 
 **第一阶段 · 初始化**
@@ -123,14 +127,15 @@ AI:   [正在分析项目 Brief...]
       ✔ 填充:    .cursor/rules/02_tech_stack.mdc    (写入项目技术决策)
       ✔ 填充:    .cursor/rules/90_custom_rules.mdc  (写入团队编码规范)
 
-      下一步：运行 /archi.scope 将需求分解为任务。
+      下一步：Brief 已覆盖全部需求 → /archi.plan <首个任务ID>
+             Brief 之外还有需求 → /archi.scope 先追加任务
 ```
 
 > **已有代码？** 改用 `/archi.inherit` —— 逆向分析项目，将已有功能注册为 `LEG-xx` 任务，并额外生成 `map.json`。
 
-**第二阶段 · 需求分解（可选）**
+**第二阶段 · 需求分解（可选，随时可跑）**
 
-> 当你的 Brief 之外还有额外需求要拆解时使用 `/archi.scope`；若 Brief 已覆盖全部需求，可直接跳到第三阶段。
+> `/archi.scope` **不是**「start 的下一步」。只要你有**除初始 Brief 之外的新功能需求**，随时可运行——start 后、项目进行中、所有任务完成后均可。
 
 ```
 你:   /archi.scope scope-brief.md          ← 提供文件；或直接 /archi.scope 触发访谈
@@ -204,7 +209,80 @@ AI:   [正在读取 代码 + spec + plan + vision + tech_stack...]
       [低] Token 过期时间未通过环境变量配置 → 建议运行 /archi.edit
 ```
 
-> **命令之间的日常开发**由自然语言 **Chat Mode** 驱动——提问、微调代码、调试——无需斜杠命令。7 个规则文件中有 4 个作为始终在线的基底规则：`00_system`、`02_tech_stack`、`90_custom_rules`、`99_context_glue`，AI 不会因会话切换而"失忆"。
+> **命令之间的日常开发**由自然语言 **Chat Mode** 驱动。用自然语言描述需求（如「加个登录功能」「修一下认证的 bug」），AI 会自动识别意图并加载对应协议（scope/plan/code/edit/fix）执行，**无需手动输入 `/archi.*` 斜杠命令**。提问、琐碎修改、调试则直接回答。7 个规则文件中有 4 个作为始终在线的基底规则：`00_system`、`02_tech_stack`、`90_custom_rules`、`99_context_glue`，AI 不会因会话切换而"失忆"。
+
+---
+
+## 教程
+
+不同场景，同一套协议。按你的情况选择对应路径。
+
+### 教程 A：新项目，Brief 已覆盖全部需求
+
+`project-brief.md` 已列出所有功能，无需 scope。
+
+```
+/archi.start project-brief.md  →  /archi.plan FEAT-001  →  /archi.code FEAT-001  →  ...
+```
+
+Start 产出 roadmap 后，直接 plan 首个任务，再 code。
+
+---
+
+### 教程 B：新项目，Brief 不完整
+
+start 跑完后发现漏了功能，或想追加更多。
+
+```
+/archi.start project-brief.md  →  /archi.scope scope-brief.md  →  /archi.plan FEAT-001  →  ...
+```
+
+Scope 向 `roadmap.json` 追加任务，再按 plan → code 继续。
+
+---
+
+### 教程 C：项目进行中追加功能
+
+FEAT-001 已做完，想加 FEAT-002、FEAT-003 等。
+
+```
+...  →  /archi.scope scope-brief.md  →  /archi.plan FEAT-002  →  /archi.code FEAT-002  →  ...
+```
+
+**Scope 随时可跑**——不限「start 之后」。只要有超出当前 roadmap 的新需求，就运行 scope。
+
+---
+
+### 教程 D：已有代码库
+
+已有仓库，想纳入 Architext 管理。
+
+```
+npx archi init  →  /archi.inherit [project-brief.md]  →  /archi.edit LEG-xx 补全 Stub  →  /archi.code LEG-xx
+```
+
+Inherit 逆向分析项目，将已有功能注册为 `LEG-xx` 任务。用 edit 补全 Stub spec，再按需 code。
+
+---
+
+### 教程 E：Bug 修复
+
+```
+/archi.fix FEAT-001 "密码含特殊字符时登录失败"
+```
+
+Fix 诊断根因，向 plan 追加 Bugfix Phase，并修复代码。
+
+---
+
+### 何时用 /archi.scope（速查）
+
+| 时机 | 操作 |
+|:---|:---|
+| start 后，Brief 未覆盖全部 | scope |
+| 项目进行中，想到新功能 | scope |
+| 所有任务 done，要加新模块 | scope |
+| Brief 已覆盖全部 | 跳过 scope，直接 plan |
 
 ---
 
@@ -212,10 +290,12 @@ AI:   [正在读取 代码 + spec + plan + vision + tech_stack...]
 
 ### AI 对话命令
 
+可通过输入 `/archi.<命令>` 或直接用自然语言描述意图触发——Chat Mode 会自动加载并执行对应协议。
+
 | 命令 | 说明 |
 |:---|:---|
 | `/archi.start [brief]` | 读取需求 Brief，生成项目基础文档（vision / roadmap / tech_stack 等） |
-| `/archi.inherit` | 逆向分析已有代码库，生成文档骨架并注册为 `LEG-xx` 任务 |
+| `/archi.inherit [brief]` | 逆向分析已有代码库；可选传 project-brief.md 补充愿景/路线图（骨架仓库） |
 | `/archi.scope [file_path]` | 将额外需求拆解为 Roadmap 任务；无文件则自动发起访谈 |
 | `/archi.plan <ID> [context]` | 深度架构访谈 → 生成 spec / plan（[?UI] 附 ui.md + ui_concept.html）；可附加已知上下文减少提问 |
 | `/archi.code <ID>` | 按 plan 分阶段实现代码；仅 `active` 任务可进入 |
@@ -278,7 +358,7 @@ Agent 模式适合单次会话。Architext 提供跨会话、跨成员、跨 AI
 
 **我的已有项目能用吗？**
 
-可以。运行 `/archi.inherit`，Architext 会分析你的现有代码并生成文档骨架。已有功能以 `LEG-xx` 形式注册为存根规格，渐进式接入，无需推倒重来。
+可以。先运行 `npx archi init` 部署框架，再运行 `/archi.inherit`，Architext 会分析你的现有代码并填充文档骨架（非覆盖既有内容）。已有功能以 `LEG-xx` 形式注册为存根规格，渐进式接入，无需推倒重来。
 
 > **注意**：`/archi.inherit` 目前处于早期阶段，对大型或复杂仓库的分析结果可能不够完整，需要手动补充。欢迎提交 Issue 反馈遇到的问题。
 
@@ -294,6 +374,8 @@ Agent 模式适合单次会话。Architext 提供跨会话、跨成员、跨 AI
 | Windsurf | `.windsurf/rules/` | `.md` | 支持 |
 | Trae | `.trae/rules/` | `.md` | 支持 |
 | VS Code | `.github/instructions/` | `.instructions.md` | 支持 |
+| Claude Code | `.claude/rules/` | `.md` | 支持 |
+| OpenCode | `.opencode/rules/` | `.md` | 支持 |
 
 后续计划扩展更多编辑器支持。