@haaaiawd/anws

English | 中文

Anws

Anws is a spec-driven workflow framework for AI-assisted development across modern AI IDEs and coding tools.

It helps teams build production-ready software through a disciplined path:

PRD -> Architecture -> ADR -> Tasks -> Review -> Code -> Upgrade

Anws enforces design-first principles, preserves context in files, and prevents architectural drift across multi-tool AI coding workflows.

TL;DR: a design-first workflow framework for AI coding tools that turns vibe coding into production-oriented engineering.

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

v2.2.2 centers the /forge chain: /forge AUTO keeps checkpoint ceremony with AUTO signatures; code-reviewer follows wave cadence (typically once per wave at the wave’s last task, with a ~2–3 wave catch-up if long skipped—not after every task by default); e2e-testing-guide is guide first, then live browser steps when tooling exists—otherwise guide-only, never claim “tested” without evidence. /change handles doc/task backflow only—it does not run code-reviewer (static fidelity stays in /forge §3.4.5 and /challenge).

v2.2.0 shipped closed-loop challenge, explicit contract closure, code-reviewer as static evidence, forge challenge-report gates, and e2e-testing-guide. Full history: RELEASE_NOTES.md · GitHub Releases.

v2.0.0 was the protocol-level major (unified .anws/, controlled AGENTS.md, multi-target projection). See RELEASE_NOTES.md for the complete major changelog.

Quick Start

Install via npm

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

• Requirement
  • Node.js >= 18
• Install behavior
  • anws init installs one or more target projections into their native folders
  • example: anws init --target windsurf,opencode

Update an Existing Project

cd your-project
anws update

• Update flags
  • anws update --check and anws update --target are removed; run anws update once to refresh all matched targets
• State source
  • anws update reads .anws/install-lock.json
  • if the lock is missing or invalid, it falls back to directory scan
  • if lock drift is detected, directory scan becomes the effective source for the current update
  • a real anws update can rebuild .anws/install-lock.json from detected targets when fallback is active
• 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
• 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/
• Upgrade record
  • every successful update refreshes .anws/changelog/
  • target state is written back to .anws/install-lock.json

Feature demos

What using Anws looks like in practice: architecture-first /genesis, human-in-the-loop requirement alignment, and skill orchestration.

Deep Thinking & Architecture Design

Interactive Requirement Alignment

Autonomous Skill Invocation

Philosophy

1. Docs first—specs keep you in command
PRD, architecture, tasks, and design land in the repo before code does—so the project doesn’t drift in aimless “vibe runs.” Scope and progress live in .anws/, 05_TASKS.md, and AGENTS.md: you stay in control of the system, not whichever chat window is open.

2. Full autonomy inside the rails
/forge AUTO is delegation with checkpoints: keep moving inside agreed contracts. Code review, e2e-testing-guide, and the rest of the template gates keep runs auditable and bounded. When a wave is executing, it’s reasonable to walk away—coffee, a walk—because confidence comes from the spec and gates, not from staring at the model.

Iteration is the product
/challenge isn’t a one-time rubber stamp; it’s repeated adversarial passes. Good products and clear ideas are sharpened over cycles—same as real shipping: each round pulls design, tasks, and implementation back into alignment.

Recommended Workflow

Use Anws as a lifecycle, not just a folder pack.

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, tasks, and implementation fidelity with adversarial pressure	Docs / tasks / code	Challenge report
/blueprint	Break architecture into executable work	PRD + architecture	05_TASKS.md
/forge	Turn approved tasks into code with challenge-report and contract gates	Tasks + review state	Working implementation
/change	In-version task/contract tweaks (controlled expansion: few new tasks)	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

Contributing

Contributions are welcome. Before opening a PR, make sure changes align with the spec-driven workflow and the target projection model.

License

MIT © 2026

Made for architects who code, and AIs who think.

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