English | 中文

⚡ What is this?

A structured workflow framework for Agentic AI assistants, designed to solve the core pain points of the Vibe Coding era.

💡 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 | AGENTS.md + versioned docs as persistent memory | | Lack of Planning | Vibe Coding skips design, creates tech debt | Mandatory design-first workflow |

🚀 Quick Start

Option A — npm CLI (Recommended)

npm install -g @haaaiawd/anws
cd your-project
anws init

Requires Node.js ≥ 18.

Option B — GitHub Release

Download the latest .zip from Releases, then copy .agent/ to your project root.

📦 Update Existing Installation

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.

Your First Project 🐣

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."

🔁 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.

Deep Thinking & Architecture Design: The AI will automatically execute the /genesis workflow, thinking deeply about project requirements and producing the PRD and architecture design.

Interactive Requirement Alignment: The AI will ask follow-up questions for ambiguous requirements to ensure the design matches your intuition.

Autonomous Task Breakdown & Execution: The AI will autonomously call necessary Skills (e.g., spec-writer, task-planner, etc.) to complete documentation and task decomposition.

🗺️ 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:

⚡ 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/
├── AGENTS.md          # 🧠 AI's anchor point
├── .agent/
│   ├── 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

🙌 Contributing

Contributions are welcome! Please read our contributing guidelines before submitting PRs.

📜 License

MIT © 2026

Made for architects who code, and AIs who think.

🧠 "Good architecture isn't written. It's designed."