architext 0.0.4 → 0.0.5

package/CHANGELOG.md

@@ -6,7 +6,33 @@ All notable changes are documented here, following [Keep a Changelog](https://ke
 
 ---
 
-## [Unreleased](https://github.com/JiuNian3219/architext/compare/v0.0.4...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
 
 ---
 

package/README.md

@@ -104,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**
@@ -126,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
@@ -207,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 |
 
 ---
 
@@ -215,6 +290,8 @@ 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.) |
@@ -281,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.
 

package/README.zh-CN.md

@@ -104,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 之后」——项目进行中、发布后均可）
 ```
 
 **第一阶段 · 初始化**
@@ -126,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 触发访谈
@@ -207,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 |
 
 ---
 
@@ -215,6 +290,8 @@ AI:   [正在读取 代码 + spec + plan + vision + tech_stack...]
 
 ### AI 对话命令
 
+可通过输入 `/archi.<命令>` 或直接用自然语言描述意图触发——Chat Mode 会自动加载并执行对应协议。
+
 | 命令 | 说明 |
 |:---|:---|
 | `/archi.start [brief]` | 读取需求 Brief，生成项目基础文档（vision / roadmap / tech_stack 等） |
@@ -281,7 +358,7 @@ Agent 模式适合单次会话。Architext 提供跨会话、跨成员、跨 AI
 
 **我的已有项目能用吗？**
 
-可以。运行 `/archi.inherit`，Architext 会分析你的现有代码并生成文档骨架。已有功能以 `LEG-xx` 形式注册为存根规格，渐进式接入，无需推倒重来。
+可以。先运行 `npx archi init` 部署框架，再运行 `/archi.inherit`，Architext 会分析你的现有代码并填充文档骨架（非覆盖既有内容）。已有功能以 `LEG-xx` 形式注册为存根规格，渐进式接入，无需推倒重来。
 
 > **注意**：`/archi.inherit` 目前处于早期阶段，对大型或复杂仓库的分析结果可能不够完整，需要手动补充。欢迎提交 Issue 反馈遇到的问题。