@haaaiawd/anws 1.2.4 → 2.0.0

package/README.md

@@ -1,10 +1,10 @@
 <div align="center">
 
-<img src="assets/logo.png" width="200" alt="Antigravity Workflow System">
+<img src="assets/logo-cli.png" width="260" alt="Anws">
 
 [![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)
+[![Version](https://img.shields.io/badge/version-v2.0.0-7FB5B6)](https://github.com/Haaaiawd/Anws/releases)
+[![Targets](https://img.shields.io/badge/Targets-Windsurf%20%7C%20Claude%20Code%20%7C%20Copilot%20%7C%20Cursor%20%7C%20Codex%20Preview%20%7C%20OpenCode-blueviolet)](https://github.com/Haaaiawd/Anws)
 
 [English](./README.md) | [中文](./README_CN.md)
 
@@ -12,26 +12,102 @@
 
 ---
 
-## ⚡ What is this?
+# Anws
 
-A **structured workflow framework** for Agentic AI assistants, designed to solve the core pain points of the Vibe Coding era.
+**Anws** is a spec-driven workflow framework for AI-assisted software development.
 
-> 💡 **TL;DR**: Stop letting AI write spaghetti code. Force it to think like an architect first.
+It gives coding agents a disciplined path:
 
-### 🎯 Problems We Solve
+`PRD -> Architecture -> ADR -> Tasks -> Review -> Code -> Upgrade`
 
-| 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                                |
+Instead of letting AI jump straight into implementation, Anws forces design, preserves context in files, and projects the right workflow assets into the native layout of your target AI IDE.
+
+> **TL;DR**: stop treating AI like an autocomplete toy. Give it architecture, constraints, and a lifecycle.
+
+## ANWS
+
+- **Axiom** — principle before implementation
+- **Nexus** — connection before fragmentation
+- **Weave** — coherence before accumulation
+- **Sovereignty** — human judgment before automation
+
+---
+
+## Why Anws Exists
+
+Modern AI coding sessions fail in predictable ways:
+
+- **Architecture drift**
+  - different sessions generate incompatible structures
+
+- **Context amnesia**
+  - a fresh chat loses system decisions, trade-offs, and task state
+
+- **Planning collapse**
+  - code gets written before requirements and interfaces are stabilized
+
+- **Unsafe upgrades**
+  - workflow files change over time, but existing projects cannot be updated cleanly
+
+Anws addresses those problems with:
+
+- **Versioned architecture docs** under `.anws/v{N}/`
+- **A root anchor file** via `AGENTS.md`
+- **Workflow-first execution** instead of prompt-only improvisation
+- **Controlled update semantics** for `AGENTS.md`, installed targets, and upgrade history
+
+---
+
+## What's New in v2.0.0
+
+`v2.0.0` is a **major release**. It is not just a template refresh; it upgrades the project protocol.
+
+- **Unified architecture root**
+  - move from split legacy roots to `.anws/`
+  - standardize versioned docs and changelog storage
+
+- **Controlled `AGENTS.md` updates**
+  - marker-based merge for modern files
+  - automatic migration for recognized legacy files
+  - safe preservation for unrecognized legacy files
+
+- **Multi-target projection model**
+  - one canonical source
+  - multiple target IDE layouts
+  - no fake sharing of physical files across targets
+
+- **Codex projection strategy update**
+  - Codex is now treated as **Preview**
+  - because Codex prompts are no longer available, Anws now packages workflow guidance into `.codex/skills/anws-system/`
+  - `/quickstart` maps to `SKILL.md`
+  - the rest of the workflow docs are exposed as `references/*.md` under the same aggregated skill
+
+- **OpenCode support**
+  - adds native projection support for `.opencode/commands/` and `.opencode/skills/`
+  - `init`, `update`, manifest ownership, drift detection, and diff flows all understand OpenCode
+
+- **Stronger `anws update` semantics**
+  - install-lock aware
+  - directory-scan fallback
+  - drift detection
+  - target-by-target update summary
+
+- **Built-in ecosystem integration**
+  - integrates `nexus-skills`
+  - adopts `nexus-mapper` as the structural analysis backbone for `/probe`
+  - completes the workflow rename from legacy `/scout` to `/probe`
+
+- **Branded CLI experience**
+  - unified logo
+  - confirmation UI
+  - changelog generation
+  - release-oriented terminal output
 
 ---
 
-## 🚀 Quick Start
+## Quick Start
 
-### Option A — npm CLI (Recommended)
+### Install via npm
 
 ```bash
 npm install -g @haaaiawd/anws
@@ -39,218 +115,177 @@ cd your-project
 anws init
 ```
 
-> Requires Node.js ≥ 18.
+- **Requirement**
+  - Node.js `>= 18`
 
-### Option B — GitHub Release
+- **Install behavior**
+  - `anws init` installs one or more target projections into their native folders
+  - example: `anws init --target windsurf,opencode`
 
-Download the latest `.zip` from [Releases](https://github.com/Haaaiawd/Antigravity-Workflow-System/releases), then copy `.agent/` to your project root.
-
-### 📦 Update Existing Installation
+### Update an Existing Project
 
 ```bash
 cd your-project
 anws update
 ```
 
-> `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.
+- **Preview mode**
+  - `anws update --check` previews grouped diffs without writing files
 
-### Your First Project 🐣
+- **State source**
+  - `anws update` reads `.anws/install-lock.json`
+  - if the lock is missing or invalid, it falls back to directory scan
 
-> **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`).
+- **`AGENTS.md` behavior**
+  - marker-based file -> update stable sections, preserve `AUTO` block
+  - recognized legacy file -> migrate into new marker-based structure
+  - unrecognized legacy file -> warn and preserve unchanged
 
-**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."
+- **Legacy migration**
+  - if a project still has `.agent/`, the CLI can guide migration to `.agents/`
+  - after successful migration, interactive mode can also ask whether to delete the old `.agent/`
 
-### 🔁 Built with Itself (Dogfooding)
+- **Upgrade record**
+  - every successful update refreshes `.anws/changelog/`
+  - target state is written back to `.anws/install-lock.json`
 
-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.
+---
 
-**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">
+## Migration Notes for Existing Users
 
-**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">
+If you used older Anws / Antigravity layouts, `v2.0.0` matters because:
 
-**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">
+- **Directory protocol changed**
+  - old references to `genesis/` and `anws/changelog/` are replaced by `.anws/`
 
----
+- **`AGENTS.md` is no longer “always skip”**
+  - it is now a controlled managed file with merge / migrate / preserve semantics
 
-## 🗺️ Decision Flowchart
+- **Target installation is explicit**
+  - Anws now models target IDEs as first-class projections
 
-```
-                    ┌─────────────────┐
-                    │  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)
-```
+If you maintain old docs or release notes, update those references before publishing new project templates.
 
 ---
 
-## 🔑 Core Principles
+## Compatibility
 
-### 1. Versioned Architecture
-> Don't "fix" architecture docs. **Evolve** them.
+Anws keeps a **single canonical workflow / skill source**, then projects it into the native directory structure expected by each tool.
 
-- `genesis/v1` → `genesis/v2` on major changes
-- Full traceability of decisions
-- No "it was always like this" mystery
+| Environment | Status | Layout |
+| --- | --- | --- |
+| **Windsurf** | ✅ Full Support | `.windsurf/workflows/` + `.windsurf/skills/` |
+| **Antigravity** | ✅ Full Support | `.agents/workflows/` + `.agents/skills/` + `AGENTS.md` |
+| **Claude Code** | ✅ Full Support | `.claude/commands/` |
+| **GitHub Copilot** | ✅ Full Support | `.github/agents/` + `.github/prompts/` |
+| **Cursor** | ✅ Supported | `.cursor/commands/` |
+| **Codex** | ⚠️ Preview | `.codex/skills/anws-system/` + `.codex/skills/<skill>/` |
+| **OpenCode** | ✅ Supported | `.opencode/commands/` + `.opencode/skills/` |
 
-### 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
+## Recommended Workflow
 
-### 3. Filesystem as Memory
-> Chat is ephemeral. Files are eternal.
+Use Anws as a lifecycle, not just a folder pack.
 
-- `AGENTS.md` = AI's anchor
-- Architecture docs = persistent decisions
-- New session recovery in 30 seconds
+| Command | Purpose | Input | Output |
+| --- | --- | --- | --- |
+| **`/quickstart`** | Route the user through the correct workflow path | Auto-detected state | Full orchestration |
+| `/genesis` | Start from zero with PRD and architecture | Vague idea | PRD, architecture, ADRs |
+| `/probe` | Analyze a legacy codebase before change | Existing code | Risk report |
+| `/design-system` | Design one system in depth | Architecture overview | System design doc |
+| `/challenge` | Review design or tasks with adversarial pressure | Docs / tasks | Challenge report |
+| `/blueprint` | Break architecture into executable work | PRD + architecture | `05_TASKS.md` |
+| `/forge` | Turn approved tasks into code | Tasks | Working implementation |
+| `/change` | Modify an existing task only | Small scoped change | Updated task/design docs |
+| `/explore` | Research ambiguous or strategic topics | Topic | Exploration report |
+| `/craft` | Create workflows, skills, and prompts | Creation request | Reusable assets |
+| `/upgrade` | Route post-update upgrade work | Update changelog | Change or genesis path |
 
 ---
 
-## 📋 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             |
+## Core Principles
 
----
+### 1. Versioned Architecture
 
-## 🛠️ Compatibility & Prerequisites
+- architecture is **evolved**, not silently edited
+- major structural changes move from `.anws/v1` to `.anws/v2`
+- ADRs preserve the reason behind the shape of the system
 
-> ⚠️ **Important**: This framework requires **Antigravity** environment with `.agent/workflows/` support.
+### 2. Filesystem as Memory
 
-| Environment     |            Status            | Notes                          |
-| --------------- | :--------------------------: | ------------------------------ |
-| **Antigravity** |         ✅ Supported          | Full workflow + skills support |
-| Claude Code     | ❌ No native workflow support |                                |
-| Cursor          |    ❌ No workflow support     |                                |
-| GitHub Copilot  |    ❌ No workflow support     |                                |
+- `AGENTS.md` is the recovery anchor
+- `.anws/v{N}/` stores durable architecture context
+- `.anws/changelog/` records upgrade history for future sessions
 
-**What is Antigravity?**
+### 3. Thinking Before Coding
 
-Antigravity is an Agentic AI coding environment that natively recognizes `.agent/workflows/` directory and can execute slash commands like `/genesis`, `/blueprint`, etc.
+- workflows force staged reasoning before implementation
+- the built-in `sequential-thinking` skill standardizes deep analysis
+- review steps exist to catch drift before code lands
 
-### 🔌 Required: Sequential Thinking MCP Server
+---
 
-This framework uses `sequentialthinking` for deep reasoning. Install it via MCP Store:
+## Project Layout
 
-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
+```bash
+your-project/
+├── .anws/
+│   ├── install-lock.json
+│   ├── changelog/
+│   └── v{N}/
+├── .windsurf/
+│   ├── workflows/
+│   └── skills/
+├── .agents/
+│   ├── workflows/
+│   └── skills/
+├── AGENTS.md
+├── .cursor/commands/
+├── .claude/commands/
+├── .github/
+│   ├── agents/
+│   └── prompts/
+└── .codex/
+    ├── prompts/
+    └── skills/
+```
 
-> 💡 Without this, workflows still work, but deep thinking features will be limited.
+> One source model. Multiple target layouts. Explicit ownership on disk.
 
 ---
 
-## ⚡ Invoke Workflows
+## Built with Itself
 
-Antigravity will automatically recognize the intent and trigger the appropriate workflow. You can use it in two ways:
+Anws is dogfooded on its own development.
 
-#### ⚡ 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
+- **Architecture design**
+  - the CLI itself was designed through `/genesis`
 
-#### 🧠 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)
+- **Task decomposition**
+  - implementation work was planned through `/blueprint`
 
----
+- **Execution**
+  - code and doc changes were driven through `/forge`
 
-## 📁 Project Structure
+This repository is both the product and a working reference implementation.
 
-```
-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
-```
+**Deep Thinking & Architecture Design**  
+<img src="assets/genesis工作流演示.jpg" width="800" alt="Genesis Workflow">
+
+**Interactive Requirement Alignment**  
+<img src="assets/与人类交互确认细节.jpg" width="800" alt="Human Interaction">
+
+**Autonomous Skill Invocation**  
+<img src="assets/自主调用skills.jpg" width="800" alt="Skills Execution">
 
-## 🙌 Contributing
+## Contributing
 
-Contributions are welcome! Please read our contributing guidelines before submitting PRs.
+Contributions are welcome. Before opening a PR, make sure changes align with the spec-driven workflow and the target projection model.
 
 ---
 
-## 📜 License
+## License
 
 [MIT](LICENSE) © 2026
 
@@ -260,6 +295,6 @@ Contributions are welcome! Please read our contributing guidelines before submit
 
 **Made for architects who code, and AIs who think.**
 
-🧠 *"Good architecture isn't written. It's designed."*
+*Good architecture isn't written. It's designed.*
 
 </div>

package/bin/cli.js

@@ -3,29 +3,33 @@
 
 const { parseArgs } = require('node:util');
 const path = require('node:path');
-const { error, info, logo } = require('../lib/output');
+const { listTargets, getTarget } = require('../lib/adapters');
+const { blank, error, info, logo } = require('../lib/output');
 
 // ─── 版本号从 package.json 读取 ─────────────────────────────────────────────
 const { version } = require(path.join(__dirname, '..', 'package.json'));
+const TARGET_IDS = listTargets().map((target) => target.id);
 
 // ─── 帮助文本 ─────────────────────────────────────────────────────────────────
 const HELP = `
-  v${version} — Antigravity Workflow System
-
 USAGE
   anws <command> [options]
 
 COMMANDS
-  init      Copy .agent/ workflow system into the current project
-  update    Update managed .agent/ files to the latest version
+  init      Install one or more target AI IDE workflow projections
+  update    Scan installed targets from install-lock or directory layout and update them
 
 OPTIONS
   -v, --version   Print version number
   -h, --help      Show this help message
+  --target        Target AI IDE(s) for \`init\`, comma-separated (${TARGET_IDS.join(', ')})
+  --check         Preview grouped update diffs without writing files or install-lock state
 
 EXAMPLES
-  anws init          # Set up workflow system in current directory
-  anws update        # Update existing workflow files to latest
+  anws init                       # Choose target IDEs and install their managed workflow projections
+  anws init --target windsurf,codex
+  anws update                     # Update all matched targets from install-lock or directory scan
+  anws update --check             # Preview grouped changes per target without writing files
 `.trimStart();
 
 // ─── 参数解析 ─────────────────────────────────────────────────────────────────
@@ -35,6 +39,8 @@ const { values, positionals } = parseArgs({
     version: { type: 'boolean', short: 'v', default: false },
     help:    { type: 'boolean', short: 'h', default: false },
     yes:     { type: 'boolean', short: 'y', default: false },
+    target:  { type: 'string' },
+    check:   { type: 'boolean', default: false },
   },
   strict: false,
   allowPositionals: true,
@@ -44,6 +50,12 @@ if (values.yes) {
   global.__ANWS_FORCE_YES = true;
 }
 
+if (values.target !== undefined) {
+  const targetIds = values.target.split(',').map((item) => item.trim()).filter(Boolean);
+  targetIds.forEach((targetId) => getTarget(targetId));
+  global.__ANWS_TARGET_IDS = Array.from(new Set(targetIds));
+}
+
 // ─── 命令路由 ─────────────────────────────────────────────────────────────────
 async function main() {
   if (values.version) {
@@ -53,7 +65,8 @@ async function main() {
 
   if (values.help || positionals.length === 0) {
     logo();
-    process.stdout.write(HELP);
+    blank();
+    console.log(HELP.trimEnd());
     process.exit(0);
   }
 
@@ -65,7 +78,7 @@ async function main() {
       break;
 
     case 'update':
-      await require('../lib/update')();
+      await require('../lib/update')({ check: values.check });
       break;
 
     default: