TaiyiForge: a nine-phase state machine for AI coding agents

The problem is not code generation, it is the missing phase order

TaiyiForge (太一炉, published to npm as oh-my-taiyiforge) targets a specific failure pattern rather than a specific language or framework. The README lists five symptoms in a table: agents skipping requirements and design to write code immediately, long sessions losing earlier context, Claude, Codex and Cursor each demanding a different workflow, nobody trusting the AI to make a call on its own, and installed skills whose real behaviour nobody can trace. Each row pairs a symptom with a stated root cause. The first row's cause is blunt: no phase constraint, so the AI always takes the shortcut. That framing tells you who this is for. It is for teams that have already accepted AI coding assistants and now want the assistant's work to be reviewable, ordered and reproducible across more than one terminal. It is not aimed at someone who wants a faster autocomplete. The README's own one-line summary is that it turns the mysticism of AI code writing into an executable, auditable engineering pipeline, and the rest of the document is spent on the executable and auditable parts.

Nine phases, three human gates, and an engine that advances the state

The mechanism is a state machine over nine named phases in a fixed order: change, requirement, design, ui-design, task, dev, test, review, integration. The README shows the chain with arrows and marks three of them as human-approved: change, design and review. Every other transition is advanced by the engine. Each phase has a declared artifact, and the README's table names them: a scope boundary for change, acceptance criteria for requirement, at least two compared options plus a decision for design, a UI/UX contract for ui-design, independently PR-able slices for task, red-then-green TDD for dev, a test evidence summary for test, cross-AI review for review, and a delivery gate for integration. Two details matter more than the list. First, ui-design is conditional: the table notes it runs only when the change touches UI, so a backend-only change is not forced through a screen contract. Second, the engine is described as refusing to let the AI approve its own gate. The README states that the --approver flag hard-blocks progression, and that a gate without a human approver is treated as no gate at all. The artifacts land in .taiyi/changes/<slug>/ as {phase}.json files plus Handlebars-rendered Markdown that runs from CHANGE.md through to CHANGELOG.md. The README notes this directory is visible locally and not committed to the repository by default, which is what makes the audit trail cheap to produce and easy to discard.

Four terminals, one vocabulary: how the cross-tool claim is implemented

The cross-tool consistency claim is not a wrapper around a shared HTTP API. It is a Skill synchronization step. The install command npx taiyi-forge-install --all is described as syncing the Skill into Claude, Cursor, OpenCode and Codex, and the README gives per-target flags: --cursor, or --claude --opencode together. The same logical command is then invoked differently per terminal. In Claude Code and Cursor it is a slash command, /taiyi:new. In Codex the README writes it as $taiyi-new. In OpenCode it is exposed as a plugin tool. The README's claim is that the vocabulary and the behaviour are identical underneath, so a team is onboarded onto a process rather than onto a terminal. That is the strongest part of the design, and also the part you should verify yourself. Slash-command registration is a host-terminal feature, and nothing in the supplied material shows what happens when a host changes its command surface between releases. The README does document a versioned command bar: a v30 recommended top bar of twenty-one commands, grouped into project (1), main chain (6), session (4), diagnostics (2), delivery (3) and umbrella (5). That version number in the docs, set against a package at v1.1.0, is a sign the command surface moves independently of the package semver.

Install is two commands; the interesting configuration is elsewhere

Getting it running is deliberately short. The README's quick start is npm install oh-my-taiyiforge, then npx taiyi-forge-install --all, then a chat command to open the first change. There is also a source path: git clone the repository, run npm install and npm run build, then node scripts/taiyi-forge.sh install --all. The first change is created with /taiyi:new "优化登录流程" and inspected with /taiyi:status. The larger entry point is /taiyi:plan, which takes a README, a PRD, a PDF or a URL and decomposes it into multiple changes. Two flags appear in the README: --auto runs the decomposition and generation without waiting, while the default half-automatic mode splits modules, recommends a profile and waits for a human to confirm before batch-creating changes. --profile=full is shown alongside a PDF input. The profile system is the main tuning surface, and the README names three tiers by intent: full for large features, lite for small fixes, nano for typos, out of ten profiles total. The release notes for v1.0.0-rc.1 describe five plugin registries (Profile, CodePattern, SSOTRule, Extractor, RunnerPolicy) unified behind a Registry<T> abstraction with three extension sources: builtin, YAML, and node_modules, with the older API kept compatible. That is where a team with non-default conventions would actually spend its configuration effort, and it is the part the README covers least.

The auto-mode skeleton shows what the engine actually emits

The most concrete evidence in the repository is the generated example under examples/translation-assistant/agent/, described as the output of a single /taiyi:plan --auto run: 79 files across 23 directories. The backend is FastAPI, laid out as app/ with controllers/v1/ for HTTP routing and validation, services/ for business orchestration including LLM calls, caching and rate limiting, strategies/ for at least two interchangeable implementations (the README names synchronous, asynchronous and streaming translation), repositories/ for data access, models/ for ORM and schemas, middleware/ for auth, logging, ratelimit and cors, adapters/ for external services such as LLM providers and Redis, and tasks/, db/, cache/, telemetry/, core/, config/ plus an alembic/env.py migration entry point. Tests are split into six unit files plus integration/, performance/ and e2e/ directories. The frontend is four files: index.html, app.js, style.css and metrics.js. Read that structure as a statement of opinion. The strategies/ directory exists because the design phase is required to compare at least two options, so the generated code has a seam where the losing option could have gone. The three-layer test split exists because the test phase must produce evidence. This is a scaffold with opinions about where variation belongs, and if your team puts that variation somewhere else, you are fighting the generator rather than using it.

Where the pipeline is the wrong tool, and what it costs to keep

The README's own comparison table concedes the trade. Against talking directly to an AI, it lists flexibility as the other side's advantage, with the note that TaiyiForge offers ten profiles to pick from. That is a real cost, not a marketing concession. Nine phases per change means nine sets of artifacts, and even with the nano profile the engine still has a state machine to advance, a gate to record and a change directory to write. For a one-line fix on a Friday afternoon, the ceremony is larger than the diff. The second limitation is structural: the approval gates are only as real as the person clicking through them. The README states that --approver hard-blocks progression, but a reviewer who approves the design phase without reading the two compared options has converted a gate into a formality, and the tool cannot detect that. Third, the README does not describe what happens when a change is partially complete and the underlying codebase moves, beyond the ChangeGraph feature, which is described only as automatically tracking dependencies between changes. The supplied material does not explain how a conflict between two in-flight changes is resolved, so treat that as unverified. Finally, the artifacts live in .taiyi/changes/<slug>/ and are not committed by default. That keeps the repository clean, but it also means the audit trail is local. If your reason for adopting this is traceability across a team, you have to decide deliberately where those files go, because the default puts them on one machine.

The honest alternative: prompt discipline plus a spec-driven generator

The alternative most teams will already be running is a hand-written workflow file checked into the repository, plus whatever the assistant's own project instructions support. In that setup the phase order lives in a Markdown document the agent is asked to follow, and enforcement is the model's willingness to comply. TaiyiForge's difference is that the order lives in a state machine that advances the change and records the artifact, so skipping a phase is a state error rather than a forgotten instruction. The second alternative is a spec-driven scaffold generator, the kind that turns a specification into a project skeleton in one pass. That produces the same category of output as /taiyi:plan --auto, and it is faster for greenfield work, but it has no notion of a change lifecycle afterward: once the skeleton exists, the generator has nothing to say about the review gate on the next feature. TaiyiForge's bet is that the value is in the repeated change, not the first scaffold, which is why the project-level /taiyi:plan command is one entry in a twenty-one-command bar and the change-level commands occupy the main chain. If your work is mostly greenfield generation, the scaffold generator is the better fit. If your work is a long-lived codebase receiving a steady stream of changes, the ordering is the part you are buying.

Licence, maintenance surface and what to check before committing

The repository is MIT licensed, which permits commercial and closed-source use and requires only that the copyright notice and permission text travel with copies or substantial portions. That is a permissive baseline, and nothing in the supplied material suggests additional terms, but the licence file itself is the authority and this is not legal advice. On maintenance cost, the observable signals are a v1.0.0 stable release in June 2026, a v1.1.0 in July 2026, and a last push in September 2026, with the README documenting a v30 command bar against a v1.1.0 package. Two versioning tracks running at different speeds is normal for a plugin that tracks four host terminals, but it means a documentation-versus-package drift is the most likely failure you will hit. The upgrade surface is also wider than a typical library: the install step writes Skill files into your terminal configuration, so an upgrade can change command names and gate behaviour in a place your build system does not see. The pragmatic check is to run npx taiyi-forge-install --all on a branch, diff the files it writes, and compare the registered command names against docs/taiyi/canonical-commands.md before merging. The README's own framing is that the pipeline is the deliverable, so evaluate it by walking one real change through all nine phases and reading the artifacts it leaves in .taiyi/changes/<slug>/, not by reading the architecture diagram.

Editorial conclusion

Adopt TaiyiForge if you already run Claude Code, Codex, Cursor or OpenCode on a codebase where unreviewed agent output has caused real rework, and you want the phase order and the approval points to live in a state machine rather than in a prompt you keep retyping. Do not adopt it for a solo spike, a throwaway script, or a repository where a nine-phase ceremony per change costs more than the change itself. Before installing, verify two things in the repo itself: that the .taiyi/changes/<slug>/ directory is genuinely excluded from version control by default, as the README states, and that docs/taiyi/canonical-commands.md matches the command names your terminal build actually registers, because the README documents a v30 command bar while the install script ships whatever the current package contains.

Official sources

1. Dong90/oh-my-taiyiforge on GitHub
2. Issues
3. License: MIT
4. README
5. Releases