oh-my-taiyiforge: a nine-stage state machine bolted onto AI coding
AI workflow automation plugin for intelligent code generation with Claude/Codex
At a glance
- What is it?
- oh-my-taiyiforge is an npm package that installs one Skill into Claude, Cursor, Codex and OpenCode and then drives every change through a fixed nine-stage pipeline with human gates at three points. What makes it more than a prompt collection is the engine underneath: a state machine that advances stages itself, artifacts per stage that land on disk, and hard constraints such as red-then-green development and an executable verification command for every acceptance criterion.
- Who is it for?
- oh-my-taiyiforge fits a team that keeps re-learning the same nine steps in four different tools and wants one enforced sequence with an audit trail, especially one that has been burned by agents skipping requirements or by long sessions losing earlier work. It does not fit a solo developer who wants a quick answer, since nine stages with three approval stops is overhead for a one-line fix, and the `nano` and `lite` profiles exist precisely because one size does not fit.
- Can I use it commercially?
- Yes. MIT is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
- Is it still maintained?
- Yes. The repository last received commits 7 days ago.
- What is it written in?
- Mainly TypeScript, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on October 5, 2026, and from our analysis. They are not legal advice.
Editorial analysis
Nine stages, and the engine is not allowed to approve itself
The pipeline is fixed, and each stage has one output and one owner:
change → requirement → design → ui-design → task → dev → test → review → integrationThe diagram marks three of those stages with a human approval gate above them.
`change` produces a proposal and scope boundary and waits for a person. `requirement` produces acceptance criteria and ACs and is engine-decided. `design` produces a comparison of at least two options plus the decision, and waits for a person again. `ui-design` produces the UI/UX contract, and only runs when UI is touched. `task` produces slices that can go out as independent pull requests. `dev` is red-then-green. `test` produces a summary of test evidence. `review` is a cross-AI review and waits for a person. `integration` is the delivery gate and is engine-decided.
Three human gates out of nine is the design in one sentence, and the README is explicit that the AI cannot let itself through. The comparison table draws the intended contrast: talking to a model directly relies on prompts and hope for process discipline, and approval happens when someone feels like it, while here `--approver` blocks and nothing ships unapproved.
Twenty-one commands, and Codex spells them differently
The same vocabulary is meant to work in four terminals: Claude Code's `/taiyi:new`, Cursor's slash command of the same name, Codex's `$taiyi-new`, and OpenCode's plugin tool. The v30 recommended top bar is 21 commands in five groups:
| Group | Commands | |----|----------| | Project (1) | `/taiyi:plan [file]`, taking a README, PRD, PDF or URL into multiple changes | | Main chain (6) | `/taiyi:new`, `/taiyi:status`, `/taiyi:write`, `/taiyi:continue`, `/taiyi:apply`, `/taiyi:archive` | | Session (4) | `/taiyi:pause`, `/taiyi:pause --resume`, `/taiyi:cancel`, `/taiyi:list` | | Troubleshooting (2) | `/taiyi:verify`, `/taiyi:render` | | Delivery (3) | `/taiyi:commit`, `/taiyi:ship`, `/taiyi:land` | | Umbrella (5) | `/taiyi:skill <name>`, `/taiyi:token`, `/taiyi:test`, `/taiyi:review`, `/taiyi:diagram` |
The main chain is the loop the demo shows: `/taiyi:new`, `/taiyi:status`, `/taiyi:write`, `/taiyi:continue` walks one stage to completion, and the demo is a 27-second terminal recording of exactly that.
The naming difference is the one concession to each tool's syntax, which is the price of the claim that you onboard by team rather than by tool.
/taiyi:plan waits for you by default, and --auto does not
There are two levels of entry. The project level is `/taiyi:plan`, which takes a whole requirement, breaks it into modules, recommends a profile for each, handles conflicts, and then hands you a batch of `/taiyi:new` invocations. The change level is `/taiyi:new`, which puts one module through the nine stages and produces a CHANGE through to CHANGELOG entry.
The default is semi-automatic: split the modules, wait for confirmation, then run the batch. Auto mode runs backend, frontend, tests and migrations in one pass, invoked as `/taiyi:plan README.md --auto`, while `/taiyi:plan PRD.pdf --profile=full` stays semi-automatic and asks for confirmation after the split.
The committed example of what auto mode produces is `examples/translation-assistant/agent/`, which the README describes as 79 files across 23 directories from a single command. Its backend is FastAPI, laid out as `app/main.py` for the entry point, `controllers/v1/` for the HTTP layer with routing and validation, `services/` for business orchestration including LLM calls, caching and rate limiting, `strategies/` for at least two replaceable strategies, named as synchronous, asynchronous and streaming translation, then `repositories/`, `models/`, `middleware/` for auth, logging, rate limiting and CORS, `adapters/` for external services such as the LLM provider and Redis, `tasks/` for async work, and `db/`.
Artifacts land in .taiyi/changes/<slug>/ and stay out of git
Each module produces its own stage artifacts under `.taiyi/changes/<slug>/`: a `{phase}.json` per stage, and a Handlebars-rendered chain of Markdown from `CHANGE.md` through to `CHANGELOG.md`. They are visible on your machine, and by default they are not committed to the repository.
That detail is the one to sit with, because it cuts both ways. A change record that stays local cannot be reviewed in a pull request, which removes the main way a team would normally inspect what the agent produced. In exchange, no generated Markdown accumulates in your history and no `.taiyi` directory ends up in a diff someone has to read.
The repository itself commits a `.taiyi/` directory at the root alongside a `.pitfalls/` directory and an `.omc/` directory, plus `FIVE_ROLES_MIGRATION.md`, `REVIEW.md` and `CHANGELOG-ARCHIVE.md`. The example set is correspondingly wide: `browser-e2e-smoke`, `clipboard-history`, `commands-smoke`, `full-flow-demo`, `todo-fullstack`, `translation-assistant`, `v28-all-slashes-demo` and `verification-suite`.
Forced TDD, evidence before passing, and token compaction
Five constraints sit under the pipeline, and they are stated as rules rather than advice.
Development is red-then-green in the `dev` stage, described as a hard constraint rather than a suggestion. Passing a stage requires evidence: every acceptance criterion has to be paired with an executable verification command, and a criterion whose command fails does not pass. Long sessions produce `CONTEXT-COMPACT.md` automatically so work resumes across days. A `ChangeGraph` tracks dependencies between changes so one edit shows its blast radius. And sizing is not one-size-fits-all: large features take the `full` profile, small fixes `lite`, typo changes `nano`, with ten profiles in total.
Five registries were unified as a `Registry<T>` abstraction in v1.0.0-rc.1: Profile, CodePattern, SSOTRule, Extractor and RunnerPolicy, each accepting builtin, YAML and `node_modules` extension sources while the old API stays compatible.
The stated position is that the project invents no new standard, and instead orchestrates Harness, OpenSpec, GStack, Superpowers, OMO and Spec-Kit into one state machine, using whatever you have installed and skipping the rest automatically.
Four binaries, a postinstall hook, and hono pinned by override
The npm manifest is where the shape of the tool becomes clear. It is an ES module package named `oh-my-taiyiforge` at version `1.1.0`, licensed MIT, with a main entry at `dist/plugin/index.js` and a second export, `./core`, pointing at `dist/core/workflow-engine.js`, which is the state machine exposed on its own.
Four executables are published: `taiyi` for the CLI, `taiyi-mcp` for the MCP server, `taiyi-forge` for a shell script wrapper, and `taiyi-forge-install` for the installer that syncs the Skill into your tools. The published `files` list includes `dist`, `skills`, `templates`, `prompts`, `scripts`, `postinstall.mjs`, `AGENTS.md`, `LICENSE` and `README.md`, so the Skill, the templates and the prompts all travel inside the package rather than being fetched separately.
Two lifecycle hooks are registered: `prepare` runs the build, and `postinstall` runs `node postinstall.mjs`. There is also a single dependency override pinning `hono` to `4.12.30`.
Tests are split across two ecosystems, `test` runs vitest and `test:py` runs `python -m pytest tests/ -v`, and `ci:platforms` chains four checks in sequence for opencode, claude, codex and cursor.
The optional backend service is Python, on port 8000, defaulting to gpt-4o-mini
Alongside the TypeScript plugin there is a Python service, and it is worth separating from the workflow machinery. The Dockerfile is a two-stage build on `python:3.11-slim` that installs `requirements.txt` into a builder, copies the result and the source into the runtime image, exposes port 8000, and starts `uvicorn app.main:app`.
The compose file is one service, `backend`, built from the repository root, mapping 8000 to 8000, with `TAIYI_LOG_LEVEL=INFO`. Note that its `env_file` points at `.env.example`, so the example file doubles as the runtime configuration in the compose path.
That file also shows the defaults a new install gets: `TAIYI_DEBUG=false`, host `0.0.0.0`, port `8000`, an OpenAI base URL of `https://api.openai.com/v1`, model `gpt-4o-mini`, temperature `0.3`, max tokens `2048`, and a rate limit of 60 requests per minute.
Installing the workflow itself is two commands, `npm install oh-my-taiyiforge` and `npx taiyi-forge-install --all`, with per-target variants like `--cursor` and `--claude --opencode`, or from source with a clone, `npm install`, `npm run build` and `node scripts/taiyi-forge.sh install --all`. The releases tell their own story: v1.0.0 and v1.0.0-rc.1 both landed on 2026-06-28, v1.1.0 on 2026-07-15, and the last push to `main` was 2026-09-28.
Editorial conclusion
oh-my-taiyiforge fits a team that keeps re-learning the same nine steps in four different tools and wants one enforced sequence with an audit trail, especially one that has been burned by agents skipping requirements or by long sessions losing earlier work. It does not fit a solo developer who wants a quick answer, since nine stages with three approval stops is overhead for a one-line fix, and the `nano` and `lite` profiles exist precisely because one size does not fit. Check three things first: that you can accept generated artifacts staying out of version control, since `.taiyi/changes/` is not committed by default and that removes the obvious review surface; which profile you start from, because `full` on a typo is the expensive mistake; and whether you want the Python backend service at all, since it is separate from the workflow engine and comes with its own model and rate-limit defaults. The four-way command parity is real but not identical, with Codex using its own prefix.
Frequently asked questions
What does oh-my-taiyiforge actually do?
It installs a Skill into your AI terminals and drives each change through a nine-stage pipeline enforced by a state machine: change, requirement, design, ui-design, task, dev, test, review, integration. A human approves at change, design and review, and the engine is not permitted to approve its own work.
How do I install oh-my-taiyiforge?
Run npm install oh-my-taiyiforge, then npx taiyi-forge-install --all to sync the Skill into Claude, Cursor, OpenCode and Codex. You can target one terminal instead, for example --cursor or --claude --opencode, or install from source with a clone followed by npm install, npm run build and node scripts/taiyi-forge.sh install --all.
What is /taiyi:plan and what does --auto change?
/taiyi:plan is the project-level entry that takes a README, PRD, PDF or URL, splits it into modules, recommends a profile for each and handles conflicts. It is semi-automatic by default, so you confirm the modules before the batch of /taiyi:new runs. With --auto it generates the backend, frontend, tests and migrations in one pass instead.
Which AI tools does oh-my-taiyiforge support?
Claude Code, Cursor, Codex and OpenCode, with the same 21 commands across all four. The command names carry each tool's own syntax, so Claude Code and Cursor use /taiyi:new while Codex uses $taiyi-new, and OpenCode reaches the same behaviour through its plugin tool.
What are the five registries in oh-my-taiyiforge?
Profile, CodePattern, SSOTRule, Extractor and RunnerPolicy, unified as a Registry<T> abstraction in v1.0.0-rc.1. Each one accepts builtin, YAML and node_modules extension sources, and the older API stays compatible so existing configurations keep working.
Official sources
Add this badge to your README
If you maintain this project, the badge below links readers to this analysis and shows its maintenance status from the daily GitHub snapshot. Paste the markdown into your README; add ?metric=license or ?metric=stars to the image URL for a different field.
[](https://hysenlabs.com/projects/dong90-oh-my-taiyiforge)