V1 · Claude Code first · Codex review · Gemini in V2 · MIT

From requirement to tested code, under control.

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

You write a requirement and approve twice. The AI does the rest, within limits.

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.

1

You write a requirement

A short Markdown file in plain language. There is no template to learn.

2

The AI works phase by phase

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.

3

You decide, twice

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

4

You get a pull request you can check

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.

A requirement from the demo, shortened: REQ-003
  • Staff can switch an active customer to inactive, and back.
  • Deactivating changes nothing else about the customer.
  • A customer cannot be reactivated while another active customer uses the same phone number.

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.

Words used on this page

  • AC, acceptance criterion: one statement of what must be true when the work is done, written so that it can be tested.
  • TC, test case: one check of an acceptance criterion, with its data and expected result.
  • Gate: a point where the workflow stops until a person approves.
  • Write scope: the files a phase may change. A check after every run (diff-scope) reverts anything else.
  • Headless: the AI runs from the command line with a fixed prompt and limited tools, with no chat window.

Workflow

One requirement, ten steps, two human gates

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.

  1. 00DiscoverMap the system from source and legacy code
  2. 01AnalysisAcceptance criteria as Given/When/Then
  3. 02Design + Test specDecisions, OpenAPI, test cases from the ACs
  4. 03Design reviewAI checks it against the requirement and the code; a critical finding sends it back, up to 3 rounds
  5. GATEHuman approves designApproval is bound to a content hash
  6. 04PlanningSmall tasks, ≤ 10 files, each with its own tests
  7. 05 · loopImplementationDeveloper → build → unit test → commit
  8. 06ReviewChecked against design, contract and standards
  9. GATEHuman merges PROn GitHub or GitLab, as usual
  10. 07Knowledge updateKeeps the map current for the next requirement
Done by AI Human gate Repeats per task, retry ≤ 3, then blocked

Replay of a real run

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
Current stepDone
AI time
69 min
Cost, API list price
27.22 USD
Tasks done
6 / 6
Human approvals
2 / 2

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

Three separate layers

Switching AI tools does not mean rewriting the process: adding Codex or Gemini is just another adapter.

Corewhat to do

Agents, skills, workflow, contracts and policies as Markdown/YAML in aiws/, neutral to any AI. Owned and reviewed by people, like code.

Orchestratorwhen it may run

The aiws CLI owns state.yaml, runs phases, validates contracts, enforces diff-scope, runs the real build and tests, and commits with traceability trailers.

Adapterwhich AI does it

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

Gates enforced by real mechanisms, not just prompts

Four independent layers. If one is bypassed, the next one still blocks.

01

Orchestrator

Agents of a locked phase are never called. Approvals are bound to content hashes; retries are capped.

02

Tool permissions

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.

03

Guard hook

PreToolUse blocks out-of-scope writes, secret reads and any attempt by the AI to approve itself, including nested shells.

04

Git + diff-scope

After every run, any file changed outside the scope is reverted and the run fails, however it was written.

Any language

Frontend, backend and legacy in any stack

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

  • Stack detection: Maven, Gradle, .NET, npm/pnpm/yarn, Python, Go, PHP, Ruby, Rust, Dart/Flutter.
  • Read-only legacy: a language summary (e.g. .cbl, .frm) feeds discovery.
  • Traceable in every framework: TC-3 attached through @DisplayName, [Trait], pytest.mark, t.Run...
  • API contract against the backend: for NestJS, Express, Fastify and Spring, 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.
Javamaven · gradle Kotlingradle C# / .NETdotnet TypeScriptnpm · pnpm · yarn Pythonpytest Gogo test PHPphpunit Rubyrspec Rustcargo Dart / Flutterflutter test Legacyread-only Other stacksdeclare commands

International standards

Standard output that never breaks your structure

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.

AreaStandard
Acceptance criteriaGiven/When/Then (Gherkin); requirement quality per ISO/IEC/IEEE 29148
Test specificationISO/IEC/IEEE 29119-3; ISTQB test design techniques (partitioning, boundary values, decision tables)
Unit testArrange-Act-Assert; framework naming; TC ids through standard metadata
CodeGoogle Java Style, .NET conventions, PEP 8, Effective Go, PSR-12, Effective Dart…
APIOpenAPI 3.x, RFC 9110, errors as RFC 9457 Problem Details, ISO 8601 timestamps
SecurityOWASP Top 10 / ASVS
CommitConventional Commits with git trailers REQ-ID · Task · Tests · AIWS-Run

Traceability

From requirement to commit, no database needed

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
ACTest caseTaskCommitResult
AC-1TC-82T1e1ba048pass
AC-1TC-84T24806b5dpass
AC-1TC-91T3b16ba82pass
AC-2TC-85T24806b5dpass
AC-2TC-92T3b16ba82pass

Real run

Results on six real requirements with Claude Code

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.

33/33
tasks passed on the first attempt
61 → 144
ACs traced to test cases, 100%
0
out-of-scope writes in 79 AI runs
2
human gates per requirement: design approval, PR merge
150+
automated tests, CI on Windows, Linux and macOS

Cost and control

You decide how much the AI may spend and when it stops

Shaped by real requirement runs on a three-language demo workspace.

Cost at a glance

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.

Budget per requirement

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.

Model per agent or phase

Use a stronger model for design and review and a cheaper one for implementation or the knowledge update, with one line in runtime.yaml.

Pause and resume

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

Up and running in a few commands

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:

  • Human-only commands (gate, approve, reject, answer, redesign, revise, resume, abandon, unlock, detect --write, new --from-issue, new --from-doc) refuse to run inside an AI session.
  • Parallel work: several requirements can run analysis and design at once with aiws new --worktree.
  • Token-free tests: the scripted adapter runs the whole workflow deterministically.
  • Your first requirement: the handbook goes through it step by step, from writing it to the merged pull request.
  • Other tools: 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.
  • A new release: aiws upgrade brings the kit of a workspace to the one the CLI ships. Files you changed are kept.
  • A requirement that changed: edit its file, then 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.
  • From a document: 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: with review_gate: reviewproof in workflow.yaml, aiws approve REQ-001 pr needs a reviewproof round that passed on the head of the requirement branch.
  • Knowledge pull request: with pull_request in runtime.yaml, aiws also pushes the knowledge update of a finished requirement and opens its pull request.
  • Base branch: 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