@haaaiawd/anws 1.2.0 → 1.2.1

package/README.md

@@ -1,96 +1,265 @@
-# anws
+<div align="center">
 
-**Antigravity Workflow System** — 一条命令，将 AI 协作工作流体系注入任意项目。
+<img src="assets/logo.png" width="200" alt="Antigravity Workflow System">
 
-```
-npm install -g @haaaiawd/anws
-anws init
-```
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
+[![Target: Antigravity](https://img.shields.io/badge/Environment-Antigravity-blueviolet)](https://github.com/google-deepmind/antigravity)
+[![Vibe Coding](https://img.shields.io/badge/Vibe%20Coding-Enabled-ff69b4)](https://github.com/karpathy/vibe-coding)
+
+[English](./README.md) | [中文](./README_CN.md)
+
+</div>
 
 ---
 
-## 安装
+## ⚡ What is this?
 
-```bash
-npm install -g @haaaiawd/anws
-```
+A **structured workflow framework** for Agentic AI assistants, designed to solve the core pain points of the Vibe Coding era.
 
-需要 **Node.js ≥ 18**。
+> 💡 **TL;DR**: Stop letting AI write spaghetti code. Force it to think like an architect first.
 
----
+### 🎯 Problems We Solve
 
-## 命令
+| Pain Point             | The Problem                                                 | Our Solution                                                   |
+| ---------------------- | ----------------------------------------------------------- | -------------------------------------------------------------- |
+| **Architecture Drift** | AI generates inconsistent patterns across the same codebase | `/genesis` forces PRD & architecture design first              |
+| **Spaghetti Code**     | AI lacks project context, writes code that doesn't fit      | Tasks include constraints & acceptance criteria                |
+| **Context Amnesia**    | New session = AI forgets all previous decisions             | `.agent/rules/agents.md` + versioned docs as persistent memory |
+| **Lack of Planning**   | Vibe Coding skips design, creates tech debt                 | Mandatory design-first workflow                                |
 
-### `anws init`
+---
+
+## 🚀 Quick Start
 
-将 `.agent/` 工作流体系复制到当前项目目录。
+### Option A — npm CLI (Recommended)
 
 ```bash
-cd my-project
+npm install -g @haaaiawd/anws
+cd your-project
 anws init
 ```
 
-- **首次初始化**：直接写入所有文件，不覆盖任何已有文件。
-- **检测到冲突**：显示已存在的托管文件数量，询问是否覆盖（默认 **N**）。  
-  确认后只会覆盖 `anws` 管理的文件，你的自定义文件不受影响。
-- **非 TTY 环境（如 CI）**：检测到冲突时自动跳过，不挂起进程。
+> Requires Node.js ≥ 18.
 
-### `anws update`
+### Option B — GitHub Release
 
-将当前项目的 `.agent/` 托管文件更新到最新版本。
+Download the latest `.zip` from [Releases](https://github.com/Haaaiawd/Antigravity-Workflow-System/releases), then copy `.agent/` to your project root.
+
+### 📦 Update Existing Installation
 
 ```bash
+cd your-project
 anws update
 ```
 
-- 仅覆盖 `anws` 管理的文件，用户自定义文件完全保留。
-- 交互式确认（默认 **N**），防止误操作。
+> `anws update` overwrites all managed workflow/skill files to the latest version while **preserving** your `agents.md`.
+> If the `agents.md` template has new content, an `agents.md.new` file will be generated for you to merge manually.
 
-### 选项
+### Your First Project 🐣
 
-| 选项 | 说明 |
-|------|------|
-| `-v`, `--version` | 打印版本号 |
-| `-h`, `--help` | 显示帮助信息 |
+> **The easiest way to start**: Just run the `/quickstart` command! The AI will automatically analyze your project state and guide you step-by-step through the entire lifecycle (from `/genesis` to `/forge`).
 
----
+**Looking for inspiration? Alternative prompt**: "I want to build a web-based macOS simulator, including Dock, top bar, and several system apps. Please start this new project from scratch according to the development process."
 
-## 无 npm 安装方式
+### 🔁 Built with Itself (Dogfooding)
 
-如果你不想全局安装，也可以直接克隆仓库手动获取模板：
+Fun fact: **This very CLI tool (`anws`) was built using its own workflows!**
+We used the `/genesis` workflow to design the CLI's architecture, and the `/forge` workflow to implement the code. This project serves as a live demonstration of what Antigravity Workflow System can achieve.
 
-```bash
-# 克隆仓库
-git clone https://github.com/Haaaiawd/Antigravity-Workflow-System.git
+**Deep Thinking & Architecture Design**: The AI will automatically execute the `/genesis` workflow, thinking deeply about project requirements and producing the PRD and architecture design.
+<img src="assets/genesis工作流演示.jpg" width="800" alt="Genesis Workflow">
+
+**Interactive Requirement Alignment**: The AI will ask follow-up questions for ambiguous requirements to ensure the design matches your intuition.
+<img src="assets/与人类交互确认细节.jpg" width="800" alt="Human Interaction">
+
+**Autonomous Task Breakdown & Execution**: The AI will autonomously call necessary Skills (e.g., `spec-writer`, `task-planner`, etc.) to complete documentation and task decomposition.
+<img src="assets/自主调用skills.jpg" width="800" alt="Skills Execution">
+
+---
 
-# 将 templates/.agent/ 复制到你的项目
-cp -r Antigravity-Workflow-System/src/anws/templates/.agent/ my-project/
+## 🗺️ Decision Flowchart
+
+```
+                    ┌─────────────────┐
+                    │  Where are you? │
+                    └────────┬────────┘
+           ┌─────────────────┼─────────────────┐
+           ▼                 ▼                 ▼
+    ┌──────────┐      ┌──────────┐      ┌──────────┐
+    │   New    │      │  Legacy  │      │ Existing │
+    │ Project  │      │ Takeover │      │  Change  │
+    └────┬─────┘      └────┬─────┘      └────┬─────┘
+         │                 │                 │
+         ▼                 ▼                 ▼
+    /genesis          /scout        Tweak existing task?
+         │                 │              /         \
+         │                 │             /           \
+         └────────┬────────┘     /change       /genesis
+                  │            (modify only)  (new tasks)
+                  ▼                │            │
+           /design-system <--------+------------+
+          (optional, recommended)
+                  |
+                  v
+            /challenge
+         (design review)
+                  |
+                  v
+             /blueprint
+                  |
+                  v
+            /challenge
+          (task review)
+                  |
+                  v
+               /forge
+          (code delivery)
 ```
 
 ---
 
-## 完成初始化后
+## 🔑 Core Principles
+
+### 1. Versioned Architecture
+> Don't "fix" architecture docs. **Evolve** them.
+
+- `genesis/v1` → `genesis/v2` on major changes
+- Full traceability of decisions
+- No "it was always like this" mystery
+
+### 2. Deep Thinking First
+> AI must think before it writes.
+
+- Workflows force multi-step reasoning via `sequentialthinking`
+- `[!IMPORTANT]` blocks as guardrails
+- No shallow, scan-and-output responses
+
+### 3. Filesystem as Memory
+> Chat is ephemeral. Files are eternal.
+
+- `AGENTS.md` = AI's anchor
+- Architecture docs = persistent decisions
+- New session recovery in 30 seconds
+
+---
+
+## 📋 Workflows
+
+| Command           | Purpose                                                 | Input             | Output                                     |
+| ----------------- | ------------------------------------------------------- | ----------------- | ------------------------------------------ |
+| **`/quickstart`** | **One-command entry: orchestrates the whole lifecycle** | Auto-detected     | Full pipeline orchestration                |
+| `/genesis`        | Start from zero, create PRD & architecture              | Vague idea        | PRD, Architecture, ADRs                    |
+| `/scout`          | Analyze legacy codebase risks                           | Existing code     | Risk report, Gap analysis                  |
+| `/design-system`  | Detailed design for a system                            | Architecture      | System Design doc                          |
+| `/challenge`      | Review Design & Tasks (intelligent detection)           | Full Docs / TASKS | Challenge Report (Graded)                  |
+| `/blueprint`      | Break architecture into tasks                           | PRD + Arch        | TASKS.md (WBS)                             |
+| `/forge`          | Execute tasks — architecture to code                    | TASKS.md          | Working code, verified                     |
+| `/change`         | Tweak existing tasks (no new tasks)                     | Minor tweak       | Updated TASKS + Design files (modify only) |
+| `/explore`        | Deep research & brainstorm                              | Topic/Question    | Exploration report                         |
+| `/craft`          | Create workflows/skills/prompts                         | Creation request  | Workflow / Skill / Prompt docs             |
+
+---
+
+## 🛠️ Compatibility & Prerequisites
+
+> ⚠️ **Important**: This framework requires **Antigravity** environment with `.agent/workflows/` support.
+
+| Environment     |            Status            | Notes                          |
+| --------------- | :--------------------------: | ------------------------------ |
+| **Antigravity** |         ✅ Supported          | Full workflow + skills support |
+| Claude Code     | ❌ No native workflow support |                                |
+| Cursor          |    ❌ No workflow support     |                                |
+| GitHub Copilot  |    ❌ No workflow support     |                                |
+
+**What is Antigravity?**
+
+Antigravity is an Agentic AI coding environment that natively recognizes `.agent/workflows/` directory and can execute slash commands like `/genesis`, `/blueprint`, etc.
+
+### 🔌 Required: Sequential Thinking MCP Server
+
+This framework uses `sequentialthinking` for deep reasoning. Install it via MCP Store:
+
+1. Open **Antigravity Editor**
+2. Click **"..."** (three dots) in the sidebar → **Additional Options**
+3. Select **MCP Servers**
+4. Open **MCP Store** and search for `sequential-thinking`
+5. Click **Add** to install
+
+> 💡 Without this, workflows still work, but deep thinking features will be limited.
+
+---
+
+## ⚡ Invoke Workflows
+
+Antigravity will automatically recognize the intent and trigger the appropriate workflow. You can use it in two ways:
 
-1. 阅读 `.agent/rules/agents.md` — 了解系统的核心法则
-2. 在你的 AI 助手中执行 `/genesis` — 启动新项目的架构设计流程
+#### ⚡ Method A: Slash Protocol (Explicit)
+Directly type the command in the chat or editor to trigger the workflow.
+- `/genesis` - Start project creation
+- `/scout` - Analyze existing codebase
+- `/blueprint` - Break down architecture into tasks
+
+#### 🧠 Method B: Intent Protocol (Implicit)
+Just speak naturally. Antigravity will automatically select and run the right workflow.
+- *"I want to start a new project for a todo app"* → Triggers `/genesis`
+- *"Help me understand this legacy code and its risks"* → Triggers `/scout`
+- *"I think there are gaps in this design, challenge it"* → Triggers `/challenge`
+- *"The architecture is ready, let's plan the tasks"* → Triggers `/blueprint`
+- *"Change the error message on the login page"* → Triggers `/change` (tweak existing task)
+- *"I need to add a back-to-top button"* → Triggers `/genesis` (requires new task)
 
 ---
 
-## 冲突处理机制
+## 📁 Project Structure
+
+```
+your-project/
+├── .agent/
+│   ├── rules/
+│   │   └── agents.md          # 🧠 AI's anchor point
+│   ├── workflows/             # Workflow definitions
+│   │   ├── genesis.md
+│   │   ├── scout.md
+│   │   ├── design-system.md
+│   │   ├── challenge.md
+│   │   ├── blueprint.md
+│   │   ├── forge.md
+│   │   ├── change.md
+│   │   ├── explore.md
+│   │   └── craft.md
+│   │
+│   └── skills/            # Reusable skills
+│       ├── concept-modeler/
+│       ├── spec-writer/
+│       ├── task-planner/
+│       └── ...
+│
+└── genesis/               # Versioned architecture docs
+    ├── v1/
+    │   ├── 01_PRD.md
+    │   ├── 02_ARCHITECTURE.md
+    │   ├── 03_ADR/
+    │   ├── 05_TASKS.md
+    │   └── 07_CHALLENGE_REPORT.md
+    └── v2/                # New version on major changes
+```
 
-`anws` 维护一份静态的**托管文件清单**（34 个文件），只有清单内的文件才会被覆盖，清单外的文件永远不会被修改。
+## 🙌 Contributing
 
-这意味着你可以安全地在 `.agent/` 目录中添加自定义工作流或技能，`anws update` 不会碰它们。
+Contributions are welcome! Please read our contributing guidelines before submitting PRs.
 
 ---
 
-## 系统要求
+## 📜 License
 
-- Node.js **≥ 18.0.0**
-- 无运行时依赖
+[MIT](LICENSE) © 2026
 
 ---
 
-## License
+<div align="center">
+
+**Made for architects who code, and AIs who think.**
+
+🧠 *"Good architecture isn't written. It's designed."*
 
-MIT
+</div>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@haaaiawd/anws",
-  "version": "1.2.0",
+  "version": "1.2.1",
   "description": "Antigravity Workflow System CLI — one command to install AI collaboration workflows into your project",
   "keywords": [
     "ai",

package/templates/.agent/workflows/quickstart.md

@@ -33,14 +33,14 @@ description: 一键启动入口。智能检测项目状态，编排 genesis →
    │   → 🆕 全新项目 → Jump to Step 1
    │
    ├── 有 genesis/v{N}/ 但无 05_TASKS.md
-   │   ├── 有 04_SYSTEM_DESIGN/ → 需要 blueprint → Jump to Step 3
+   │   ├── 有 04_SYSTEM_DESIGN/ → 需要 blueprint 或设计审查 → Jump to Step 3
    │   └── 无 04_SYSTEM_DESIGN/ → 可能需要 design-system → Jump to Step 2
    │
    ├── 有 05_TASKS.md 但无 src/ 代码
-   │   → 需要开始执行 → Jump to Step 5
+   │   → 需要任务审查或开始执行 → Jump to Step 5
    │
    └── 有代码 + 有任务
-       → 增量模式 → Jump to Step 6
+       → 增量模式 → Jump to Step 7
 ```
 
 ### 状态报告
@@ -80,8 +80,8 @@ description: 一键启动入口。智能检测项目状态，编排 genesis →
 - 📄 genesis/v{N}/02_ARCHITECTURE_OVERVIEW.md — {Z} 个系统
 - 📁 genesis/v{N}/03_ADR/ — {W} 个架构决策记录
 
-**下一步**: Step 2 — 系统详细设计 (如需要) 或 Step 3 — 任务拆解
-**预估**: Step 2 每个系统约 30-60 分钟; Step 3 约 20-40 分钟
+**下一步**: Step 2 — 系统详细设计 (如需要) 或 Step 3 — 设计审查 (Challenge)
+**预估**: Step 2 每个系统约 30-60 分钟; Step 3 约 15-30 分钟
 ```
 
 ⏸️ **等待用户确认** → 用户确认后进入 Step 2。
@@ -96,11 +96,11 @@ description: 一键启动入口。智能检测项目状态，编排 genesis →
 
 检查 `02_ARCHITECTURE_OVERVIEW.md` 中的系统数量和复杂度：
 
-| 条件 | 判断 | 建议 |
-|------|------|------|
-| 系统数 ≤ 2，且无复杂跨系统交互 | 简单项目 | 建议跳过，blueprint 时可按需补充 |
-| 系统数 ≥ 3，或有复杂状态同步 | 复杂项目 | 建议为每个核心系统执行 /design-system |
-| 包含 AI/LLM 集成 | 需要详细设计 | 至少为 AI 相关系统做设计 |
+| 条件                           | 判断         | 建议                                  |
+| ------------------------------ | ------------ | ------------------------------------- |
+| 系统数 ≤ 2，且无复杂跨系统交互 | 简单项目     | 建议跳过，blueprint 时可按需补充      |
+| 系统数 ≥ 3，或有复杂状态同步   | 复杂项目     | 建议为每个核心系统执行 /design-system |
+| 包含 AI/LLM 集成               | 需要详细设计 | 至少为 AI 相关系统做设计              |
 
 ### 展示评估结果
 
@@ -109,11 +109,11 @@ description: 一键启动入口。智能检测项目状态，编排 genesis →
 
 **架构中包含 {N} 个系统**:
 
-| 系统 | 复杂度 | 建议 |
-|------|:------:|------|
-| {system-1} | 🔴 高 | 建议执行 /design-system |
-| {system-2} | 🟡 中 | 可选 |
-| {system-3} | 🟢 低 | 可跳过 |
+| 系统       | 复杂度 | 建议                    |
+| ---------- | :----: | ----------------------- |
+| {system-1} |  🔴 高  | 建议执行 /design-system |
+| {system-2} |  🟡 中  | 可选                    |
+| {system-3} |  🟢 低  | 可跳过                  |
 
 **建议**: 为 {system-1} 执行详细设计。其余可在 blueprint 阶段按需补充。
 ```
@@ -122,16 +122,51 @@ description: 一键启动入口。智能检测项目状态，编排 genesis →
 
 ---
 
-## Step 3: 任务拆解 (Blueprint)
+## Step 3: 设计审查 (Challenge Design)
 
-**目标**: 执行 `/blueprint`，将架构拆解为可执行的 WBS 任务清单。
+**目标**: 执行 `/challenge`，对当前的 PRD 和架构/系统设计进行系统性审查。
+
+> 引导用户执行 `/challenge` 工作流。由于当前无 `05_TASKS.md`，系统会自动进入 `DESIGN` 模式。
+
+### 完成后展示
+
+```markdown
+## ✅ Step 3 完成: 设计审查
+
+**审查结果**:
+| 级别       | 数量  |
+| ---------- | :---: |
+| 🔴 Critical |  {X}  |
+| 🟠 High     |  {Y}  |
+| 🟡 Medium   |  {Z}  |
+| 🟢 Low      |  {W}  |
+
+**详细报告**: genesis/v{N}/07_CHALLENGE_REPORT.md
+```
+
+### 判断逻辑
+
+- **有 CRITICAL 问题**: "⚠️ 发现 {X} 个阻塞设计问题，建议先通过 /change 修复后再进入拆解环节。"
+- **无 CRITICAL**: "✅ 无阻塞问题。可以开始拆解任务。"
+
+```markdown
+**下一步**: Step 4 — 任务拆解 (Blueprint)
+```
+
+⏸️ **等待用户确认** → 用户确认后进入 Step 4。
+
+---
+
+## Step 4: 任务拆解 (Blueprint)
+
+**目标**: 执行 `/blueprint`，将稳固的架构拆解为可执行的 WBS 任务清单。
 
 > 引导用户执行 `/blueprint` 工作流。含 User Story Overlay 交叉验证。
 
 ### 完成后展示
 
 ```markdown
-## ✅ Step 3 完成: 任务清单
+## ✅ Step 4 完成: 任务清单
 
 **产出文件**: genesis/v{N}/05_TASKS.md
 
@@ -145,49 +180,41 @@ description: 一键启动入口。智能检测项目状态，编排 genesis →
 - {covered}/{total} US 完整覆盖
 - {gaps} 个覆盖 GAP (已在 Overlay 中标注)
 
-**下一步**: Step 4 — 质量审查 (建议执行，约 15-30 分钟)
+**下一步**: Step 5 — 任务审查 (Challenge Tasks，建议执行)
 ```
 
-⏸️ **等待用户确认** → 用户确认后进入 Step 4。
+⏸️ **等待用户确认** → 用户确认后进入 Step 5。
 
 ---
 
-## Step 4: 质量审查 (Challenge)
+## Step 5: 任务审查 (Challenge Tasks)
 
-**目标**: 执行 `/challenge`，对设计和任务进行系统性审查。
+**目标**: 再次执行 `/challenge`，这次专注于任务清单的完备性与覆盖率。
 
-> 引导用户执行 `/challenge` 工作流（含 design-reviewer + task-reviewer）。
+> 引导用户执行 `/challenge` 工作流。由于 `05_TASKS.md` 已存在，它将执行 `task-reviewer` (或 `FULL` 全面审查)。
 
 ### 完成后展示
 
 ```markdown
-## ✅ Step 4 完成: 质量审查
-
-**审查结果**:
-| 级别 | 数量 |
-|------|:----:|
-| 🔴 Critical | {X} |
-| 🟠 High | {Y} |
-| 🟡 Medium | {Z} |
-| 🟢 Low | {W} |
+## ✅ Step 5 完成: 任务审查
 
-**详细报告**: genesis/v{N}/07_CHALLENGE_REPORT.md
+**审查结果**: (同上表)
+**报告已追加至**: genesis/v{N}/07_CHALLENGE_REPORT.md
 ```
 
 ### 判断逻辑
-
-- **有 CRITICAL 问题**: "⚠️ 发现 {X} 个阻塞问题，建议先通过 /change 修复后再继续执行。"
-- **无 CRITICAL**: "✅ 无阻塞问题。可以开始执行。"
+- **有任务覆盖 GAP 或缺陷**: "⚠️ 任务清单有漏洞，建议使用 /change 补全。"
+- **无阻塞问题**: "✅ 任务清单坚如磐石。"
 
 ```markdown
-**下一步**: Step 5 — 开始编码执行 (Wave 1)
+**下一步**: Step 6 — 开始编码执行 (Wave 1)
 ```
 
-⏸️ **等待用户确认** → 用户确认后进入 Step 5。
+⏸️ **等待用户确认** → 用户确认后进入 Step 6。
 
 ---
 
-## Step 5: 开始执行 (Forge)
+## Step 6: 开始执行 (Forge)
 
 **目标**: 引导进入 `/forge` 的第一个波次。
 
@@ -200,10 +227,10 @@ description: 一键启动入口。智能检测项目状态，编排 genesis →
 
 基于任务清单和依赖关系，建议 Wave 1 包含:
 
-| 任务 | 标题 | 估时 |
-|------|------|:----:|
-| T{X.Y.Z} | ... | Xh |
-| T{X.Y.Z} | ... | Xh |
+| 任务     | 标题 | 估时  |
+| -------- | ---- | :---: |
+| T{X.Y.Z} | ...  |  Xh   |
+| T{X.Y.Z} | ...  |  Xh   |
 
 **总估时**: ~{T}h
 
@@ -215,7 +242,7 @@ description: 一键启动入口。智能检测项目状态，编排 genesis →
 
 ---
 
-## Step 6: 增量模式 (Incremental)
+## Step 7: 增量模式 (Incremental)
 
 **目标**: 项目已有进度时，展示当前状态并建议下一步。
 
@@ -228,10 +255,10 @@ description: 一键启动入口。智能检测项目状态，编排 genesis →
 **任务进度**: {completed}/{total} ({percentage}%)
 **当前波次**: Wave {W} ({status})
 
-| Sprint | 任务数 | 已完成 | 状态 |
-|--------|:-----:|:-----:|:----:|
-| S1 | {X} | {Y} | ✅/🔶/⬜ |
-| S2 | {X} | {Y} | ✅/🔶/⬜ |
+| Sprint | 任务数 | 已完成 | 状态  |
+| ------ | :----: | :----: | :---: |
+| S1     |  {X}   |  {Y}   | ✅/🔶/⬜ |
+| S2     |  {X}   |  {Y}   | ✅/🔶/⬜ |
 
 **建议下一步**:
 1. `/forge` — 继续执行未完成的任务