AIWS (AI Software Factory) turns a requirement into tested code in an existing system that spans several repositories, with read-only legacy code beside them, and a person approves the design before any code is written. AI agents work through explicit phases: analysis, design with a test specification, small task-by-task implementation with unit tests, then review. Every step is limited to its write scope and every output lives in git.
In short
There is no chat to supervise. The work moves through fixed phases, and every result is a file in your repository that you can read, review and revert.
A short Markdown file in plain language. There is no template to learn.
It turns the requirement into acceptance criteria, a design and a test specification, then writes the code in small tasks, each with its unit tests, and reviews the result. In each phase it may change only the files of that phase; any other change is reverted. Before you see the design, an AI reviewer checks it and sends it back while a critical finding is open.
First you read the design and the test specification and approve them, or send them back with a note. Later you review and merge the pull request. The AI cannot run these two commands. When a run stops at a gate in your terminal, a menu asks for the decision: pick it with the arrow keys. At the pull request gate it can also send the review comments of the pull request back to the AI for rework (aiws reject REQ pr --from-pr).
Code with passing unit tests, a matrix that links every acceptance criterion to its tests, task and commit, and a record of every AI run: its prompt, cost and changed files.
On the demo workspace, six real requirements each took 3 to 7 tasks, 60 to 90 minutes of AI time and 25 to 41 USD at API list prices. Rerun with 0.7.0, one of them took 13 minutes and 4.31 USD up to the pull request.
Workflow
A deterministic orchestrator decides which phase may run; the AI never changes state on its own. People step in at two gates only: approving the design and merging the PR.
blocked
REQ-003 on the demo workspace: 69 minutes of AI time, replayed in about one minute. The lines are the real output of the orchestrator, and the steps above light up as it goes.
Press Play to watch the run.$ aiws new REQ-003REQ-003 created on branch aiws/REQ-003 (base demo @ 7a881fa). Next: aiws run REQ-003$ aiws run REQ-003[REQ-003] analysis / analyst (attempt 1/3) ok -> design[REQ-003] design / architect (attempt 1/3) ok -> design[REQ-003] design / test-designer (attempt 1/3) ok -> design_approval (waiting_human)REQ-003: phase=design_approval status=waiting_human design ready for review: 02-design.md, 03-test-spec.md, api-contract.yaml. Then run `aiws approve REQ-003 design` or `aiws reject REQ-003 design -m "..."`$ aiws approve REQ-003 design$ aiws run REQ-003[REQ-003] planning / planner (attempt 1/3) ok -> implementation[REQ-003] implementation / T1 (attempt 1/3) T1 done (e1ba048)[REQ-003] implementation / T2 (attempt 1/3) T2 done (4806b5d)[REQ-003] implementation / T3 (attempt 1/3) T3 done (b16ba82)[REQ-003] implementation / T4 (attempt 1/3) T4 done (4529e7c)[REQ-003] implementation / T5 (attempt 1/3) T5 done (e3e496e)[REQ-003] implementation / T6 (attempt 1/3) T6 done (03dfd36)[REQ-003] review / reviewer (attempt 1/2) ok -> pr_approval (waiting_human)REQ-003: phase=pr_approval status=waiting_human open a PR for the branch; after it is merged run `aiws approve REQ-003 pr` (or `aiws reject REQ-003 pr -m "..."`)$ aiws approve REQ-003 pr$ aiws run REQ-003[REQ-003] knowledge_update / discovery (attempt 1/2) ok -> done (done)REQ-003: phase=done status=done
Your turn: you read the design and the test specification, then approve.
Your turn: you review and merge the pull request, then confirm.
A recording, not a live system: this page is static. Models in this run: Opus for analysis, design, planning and review, Sonnet for the developer and the knowledge update.
Architecture
Switching AI tools does not mean rewriting the process: adding Codex or Gemini is just another adapter.
Agents, skills, workflow, contracts and policies as Markdown/YAML in aiws/, neutral to any AI. Owned and reviewed by people, like code.
The aiws CLI owns state.yaml, runs phases, validates contracts, enforces diff-scope, runs the real build and tests, and commits with traceability trailers.
claude runs Claude Code headless with limited permissions; scripted runs deterministically for token-free tests; codex can take the review, so another model checks the code. V2: Gemini.
Enforcement
Four independent layers. If one is bypassed, the next one still blocks.
Agents of a locked phase are never called. Approvals are bound to content hashes; retries are capped.
Each headless run gets only the tools it needs; shell access is derived from the project's own build and test commands. None of your own plugins, skills or MCP servers is loaded, which keeps each turn about 20k tokens smaller.
PreToolUse blocks out-of-scope writes, secret reads and any attempt by the AI to approve itself, including nested shells.
After every run, any file changed outside the scope is reverted and the run fails, however it was written.
Any language
The orchestrator assumes no stack. aiws detect inspects every source-* folder and proposes build and test commands; add as many sides as you need (fe, be, mobile, worker...).
.cbl, .frm) feeds discovery.TC-3 attached through @DisplayName, [Trait], pytest.mark, t.Run...aiws detect proposes an optional openapi-drift check (commands.api_contract_be). A contract operation that no backend route serves becomes a critical review finding.International standards
The project's own conventions come first, then the language's official style guide. Renaming, moving or reformatting outside the approved design is reported by the reviewer.
| Area | Standard |
|---|---|
| Acceptance criteria | Given/When/Then (Gherkin); requirement quality per ISO/IEC/IEEE 29148 |
| Test specification | ISO/IEC/IEEE 29119-3; ISTQB test design techniques (partitioning, boundary values, decision tables) |
| Unit test | Arrange-Act-Assert; framework naming; TC ids through standard metadata |
| Code | Google Java Style, .NET conventions, PEP 8, Effective Go, PSR-12, Effective Dart… |
| API | OpenAPI 3.x, RFC 9110, errors as RFC 9457 Problem Details, ISO 8601 timestamps |
| Security | OWASP Top 10 / ASVS |
| Commit | Conventional Commits with git trailers REQ-ID · Task · Tests · AIWS-Run |
Traceability
Only consistent ids, commit trailers and evidence files in the repository. aiws trace builds the matrix; an AC without a test or a test without a commit blocks the review phase.
# git log -1 e1ba048
feat(REQ-003): T1 be - thêm thao tác ghi updateStatus chỉ đổi status vào repository
REQ-ID: REQ-003
Task: T1
Tests: TC-82, TC-83
AIWS-Run: run-0005
| AC | Test case | Task | Commit | Result |
|---|---|---|---|---|
| AC-1 | TC-82 | T1 | e1ba048 | pass |
| AC-1 | TC-84 | T2 | 4806b5d | pass |
| AC-1 | TC-91 | T3 | b16ba82 | pass |
| AC-2 | TC-85 | T2 | 4806b5d | pass |
| AC-2 | TC-92 | T3 | b16ba82 | pass |
Real run
Six requirements on a Java backend, a JavaScript frontend and a PHP legacy system, each run headless from analysis to the knowledge update with the guard hook enabled.
Cost and control
Shaped by real requirement runs on a three-language demo workspace.
aiws status shows the AI runs of a requirement, their total time and the cumulative cost per phase. aiws stats compares requirements, aiws estimate prices one before it runs, aiws report writes one HTML page per requirement, and aiws board puts every requirement on one page, live in the browser with --serve.
Set a limit in policies.yaml. Once it is reached the requirement is blocked, and only a human can raise it, also ahead of time at an approval gate.
Use a stronger model for design and review and a cheaper one for implementation or the knowledge update, with one line in runtime.yaml.
aiws stop ends a run after its current step. An interrupted run continues where it left off, and a run that reaches the AI usage limit pauses instead of failing. aiws run --wait waits the limit out and goes on, and a notify command or webhook tells you when a gate needs you.
Get started
Requires Node.js ≥ 22, Git and a signed-in Claude Code. Put your code into source-fe/, source-be/ and source-legacy/, as plain folders or git submodules, then:
gate, approve, reject, answer, redesign, revise, resume, abandon, unlock, detect --write, new --from-issue, new --from-doc) refuse to run inside an AI session.aiws new --worktree.scripted adapter runs the whole workflow deterministically.aiws sync codex, aiws sync opencode and aiws sync antigravity generate the agents and skills of the project for those tools, with the guard hook for OpenCode and Antigravity.aiws upgrade brings the kit of a workspace to the one the CLI ships. Files you changed are kept.aiws revise REQ-001 -m REASON records the revision and runs analysis and design again, behind the design gate. A finished requirement reopens on a new branch.aiws new REQ-001 --from-doc spec.docx writes the requirement from a Word, PDF, Excel, PowerPoint, HTML, text or CSV document, read with document-reader (installed separately).review_gate: reviewproof in workflow.yaml, aiws approve REQ-001 pr needs a reviewproof round that passed on the head of the requirement branch.pull_request in runtime.yaml, aiws also pushes the knowledge update of a finished requirement and opens its pull request.aiws new REQ-001 --base BRANCH names the branch the pull request goes into. A local branch without a remote, such as a worktree slot's task branch, falls back to base_branch of workflow.yaml.# install the CLI from npm, create a workspace $ npm install -g aiws-factory $ aiws init my-project && cd my-project && git init # detect stacks, generate Claude config, map the system $ aiws detect --write $ aiws sync claude $ aiws discover # one requirement $ aiws new REQ-001 # or: aiws new REQ-001 --from-issue 12 $ aiws run REQ-001 # stops at the design gate $ aiws approve REQ-001 design $ aiws run REQ-001 # stops at the PR gate $ aiws approve REQ-001 pr # after the merge $ aiws run REQ-001 && aiws trace REQ-001