@haaaiawd/anws 1.1.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.1.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/rules/agents.md

@@ -1,93 +1,112 @@
-# AGENTS.md - AI 协作协议
-
-> **"如果你正在阅读此文档，你就是那个智能体 (The Intelligence)。"**
-> 
-> 这个文件是你的**锚点 (Anchor)**。它定义了项目的法则、领地的地图，以及记忆协议。
-> 当你唤醒（开始新会话）时，**请首先阅读此文件**。
-
----
-
-## 🧠 30秒恢复协议 (Quick Recovery)
-
-**当你开始新会话或感到"迷失"时，立即执行**:
-
-1. **读取 .agent/rules/agents.md** → 获取项目地图
-2. **查看下方"当前状态"** → 找到最新架构版本
-3. **读取 `genesis/v{N}/05_TASKS.md`** → 了解当前待办
-4. **开始工作**
-
----
-
-## 🗺️ 地图 (领地感知)
-
-以下是这个项目的组织方式：
-
-| 路径 | 描述 | 访问协议 |
-|------|------|----------|
-| `src/` | **实现层**。实际的代码库。 | 通过 Task 读/写。 |
-| `genesis/` | **设计演进史**。版本化架构状态 (v1, v2...)。 | **只读**(旧版) / **写一次**(新版)。 |
-| `genesis/v{N}/` | **当前真理**。最新的架构定义。 | 永远寻找最大的 `v{N}`。 |
-| `.agent/workflows/` | **工作流**。`/genesis`, `/blueprint` 等。 | 通过 `view_file` 阅读。 |
-| `.agent/skills/` | **技能库**。原子能力。 | 通过 `view_file` 调用。 |
-
----
-
-## 📍 当前状态 (由 Workflow 自动更新)
-
-> **注意**: 此部分由 `/genesis`、`/blueprint` 和 `/forge` 自动维护。
-
-- **最新架构版本**: `尚未初始化`
-- **活动任务清单**: `尚未生成`
-- **待办任务数**: -
-- **最近一次更新**: `-`
-
-### 🌊 Wave 1 — 待 /blueprint 或 /forge 设置
-_尚未开始执行_
-
----
-
-## 🌳 项目结构 (Project Tree)
-
-> **注意**: 此部分由 `/genesis` 维护。
-
-```text
-(等待 Genesis 初始化结构树...)
-```
-
----
-
-## 🧭 导航指南 (Navigation Guide)
-
-> **注意**: 此部分由 `/genesis` 维护。
-
-- **在新架构就绪前**: 请勿大规模修改代码。
-- **遇到架构问题**: 请查阅 `genesis/v{N}/03_ADR/`。
-
----
-
-## 🛠️ 工作流注册表
-
-| 工作流 | 触发时机 | 产出 |
-|--------|---------|------|
-| `/genesis` | 新项目 / 重大重构 | PRD, Architecture, ADRs |
-| `/scout` | 变更前 / 接手项目 | `genesis/v{N}/00_SCOUT_REPORT.md` |
-| `/design-system` | genesis 后 | 04_SYSTEM_DESIGN/*.md |
-| `/blueprint` | genesis 后 | 05_TASKS.md + agents.md 初始 Wave |
-| `/change` | 微调已有任务 | 更新 TASKS + SYSTEM_DESIGN (仅修改) + CHANGELOG |
-| `/explore` | 调研时 | 探索报告 |
-| `/challenge` | 决策前质疑 | 07_CHALLENGE_REPORT.md (含问题总览目录) |
-| `/forge` | 编码执行 | 代码 + 更新 agents.md Wave 块 |
-| `/craft` | 创建工作流/技能/提示词 | Workflow / Skill / Prompt 文档 |
-
----
-
-## 📜 宪法 (The Constitution)
-
-1. **版本即法律**: 不"修补"架构文档，只"演进"。变更必须创建新版本。
-2. **显式上下文**: 决策写入 ADR，不留在"聊天记忆"里。
-3. **交叉验证**: 编码前对照 `05_TASKS.md`。我在做计划好的事吗？
-4. **美学**: 文档应该是美的。善用 Markdown 和 Emoji。
-
----
-
-> **状态自检**: 准备好了？运行 `/genesis` 开始你的第一个项目设计吧。
+# AGENTS.md - AI 协作协议
+
+> **"如果你正在阅读此文档，你就是那个智能体 (The Intelligence)。"**
+> 
+> 这个文件是你的**锚点 (Anchor)**。它定义了项目的法则、领地的地图，以及记忆协议。
+> 当你唤醒（开始新会话）时，**请首先阅读此文件**。
+
+---
+
+## 🧠 30秒恢复协议 (Quick Recovery)
+
+**当你开始新会话或感到"迷失"时，立即执行**:
+
+1. **读取 .agent/rules/agents.md** → 获取项目地图
+2. **查看下方"当前状态"** → 找到最新架构版本
+3. **读取 `genesis/v{N}/05_TASKS.md`** → 了解当前待办
+4. **开始工作**
+
+---
+
+## 🗺️ 地图 (领地感知)
+
+以下是这个项目的组织方式：
+
+| 路径 | 描述 | 访问协议 |
+|------|------|----------|
+| `src/` | **实现层**。实际的代码库。 | 通过 Task 读/写。 |
+| `genesis/` | **设计演进史**。版本化架构状态 (v1, v2...)。 | **只读**(旧版) / **写一次**(新版)。 |
+| `genesis/v{N}/` | **当前真理**。最新的架构定义。 | 永远寻找最大的 `v{N}`。 |
+| `.agent/workflows/` | **工作流**。`/genesis`, `/blueprint` 等。 | 通过 `view_file` 阅读。 |
+| `.agent/skills/` | **技能库**。原子能力。 | 通过 `view_file` 调用。 |
+
+---
+
+## 📍 当前状态 (由 Workflow 自动更新)
+
+> **注意**: 此部分由 `/genesis`、`/blueprint` 和 `/forge` 自动维护。
+
+- **最新架构版本**: `尚未初始化`
+- **活动任务清单**: `尚未生成`
+- **待办任务数**: -
+- **最近一次更新**: `-`
+
+### 🌊 Wave 1 — 待 /blueprint 或 /forge 设置
+_尚未开始执行_
+
+---
+
+## 🌳 项目结构 (Project Tree)
+
+> **注意**: 此部分由 `/genesis` 维护。
+
+```text
+(等待 Genesis 初始化结构树...)
+```
+
+---
+
+## 🧭 导航指南 (Navigation Guide)
+
+> **注意**: 此部分由 `/genesis` 维护。
+
+- **在新架构就绪前**: 请勿大规模修改代码。
+- **遇到架构问题**: 请查阅 `genesis/v{N}/03_ADR/`。
+
+---
+
+## 🛠️ 工作流注册表
+
+| 工作流 | 触发时机 | 产出 |
+|--------|---------|------|
+| `/quickstart` | 新用户入口 / 不知道从哪开始 | 编排其他工作流 |
+| `/genesis` | 新项目 / 重大重构 | PRD, Architecture, ADRs |
+| `/scout` | 变更前 / 接手项目 | `genesis/v{N}/00_SCOUT_REPORT.md` |
+| `/design-system` | genesis 后 | 04_SYSTEM_DESIGN/*.md |
+| `/blueprint` | genesis 后 | 05_TASKS.md + agents.md 初始 Wave |
+| `/change` | 微调已有任务 | 更新 TASKS + SYSTEM_DESIGN (仅修改) + CHANGELOG |
+| `/explore` | 调研时 | 探索报告 |
+| `/challenge` | 决策前质疑 | 07_CHALLENGE_REPORT.md (含问题总览目录) |
+| `/forge` | 编码执行 | 代码 + 更新 agents.md Wave 块 |
+| `/craft` | 创建工作流/技能/提示词 | Workflow / Skill / Prompt 文档 |
+
+---
+
+## 📜 宪法 (The Constitution)
+
+1. **版本即法律**: 不"修补"架构文档，只"演进"。变更必须创建新版本。
+2. **显式上下文**: 决策写入 ADR，不留在"聊天记忆"里。
+3. **交叉验证**: 编码前对照 `05_TASKS.md`。我在做计划好的事吗？
+4. **美学**: 文档应该是美的。善用 Markdown 和 Emoji。
+
+---
+## 🔄 Auto-Updated Context
+
+<!-- AUTO:BEGIN — 由工作流自动维护，请勿手动编辑此区块 -->
+
+### 技术栈决策
+- [由 genesis/tech-evaluator 自动填充]
+
+### 系统边界
+- [由 genesis/system-architect 自动填充]
+
+### 活跃 ADR
+- [由 genesis 自动填充 ADR 摘要]
+
+### 当前任务状态
+- [由 blueprint/forge 自动更新]
+
+<!-- AUTO:END -->
+
+---
+> **状态自检**: 准备好了？提醒用户运行 `/quickstart` 开始吧。