oh-my-taiyiforge 0.42.0

package/AGENTS.md

@@ -0,0 +1,46 @@
+# TaiyiForge (oh-my-taiyiforge)
+
+开源 AI 研发工作流：**OpenCode** 插件 + **Claude / Codex / Cursor** 共用 `taiyi-*` Skill 与 `.taiyi/changes/<slug>/` 工件契约。
+
+## 从这里读
+
+| 目的 | 文档 |
+|------|------|
+| **5 分钟跑通** | [`docs/QUICKSTART.md`](docs/QUICKSTART.md) |
+| **斜杠命令真源** | [`docs/taiyi/canonical-commands.md`](docs/taiyi/canonical-commands.md)（**v28 顶栏**）· [`docs/taiyi/commands.yaml`](docs/taiyi/commands.yaml) |
+| **控制面 / Agent 纪律** | [`docs/taiyi/control-plane.md`](docs/taiyi/control-plane.md) |
+| **工件目录** | [`docs/taiyi/artifact-layout.md`](docs/taiyi/artifact-layout.md) |
+| **架构** | [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md) |
+| **Skill 融合原则** | [`docs/taiyi/skill-fusion-principles.md`](docs/taiyi/skill-fusion-principles.md) |
+| **贡献** | [`CONTRIBUTING.md`](CONTRIBUTING.md) |
+
+## 硬约定（摘要）
+
+1. 每个变更一个 slug：`.taiyi/changes/<slug>/`
+2. 九阶段顺序见 `docs/taiyi/phases.yaml` — **上一阶段未完成不得进入下一阶段**
+3. 过关须 **人工审批** + **质量门禁五维**（`docs/taiyi/quality-gate.yaml`）
+4. **dev 阶段 TDD**：先失败测试，再最小实现
+5. **Token 纪律**：清 slug → archive → `token compress` → E2E/全量测试走 CI 后台（对话只写 TEST.md 摘要）
+6. **上下文加载**：进入阶段时优先读 `PHASE-CONTEXT.md`（引擎自动生成，~500 tokens），**不要**逐份读 CHANGE/REQUIREMENT/DESIGN/TASK 等上游工件
+
+## Agent 读状态（默认）
+
+```bash
+scripts/taiyi-forge.sh status [slug] --json --compact
+```
+
+解析 **`engineTruth`**，勿全量读工件进聊天。人类用户要可读摘要时用无前缀 `status` 或 `--compact`（无 `--json`）。
+
+排查：`doctor --json --compact` · `audit --json --compact`（仅失败项 / high findings）。Cursor 可用 MCP `taiyi_doctor` / `taiyi_audit`。
+
+## 安装（一行）
+
+```bash
+npx taiyi-forge-install --all   # 23 个 taiyi-* Skill → 四端
+```
+
+细节见 **QUICKSTART**；引擎 shell：`scripts/taiyi-forge.sh` · [`docs/taiyi/control-plane.md`](docs/taiyi/control-plane.md)
+
+## 许可
+
+MIT — 见 [`LICENSE`](LICENSE)

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 TaiyiForge contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.en.md

@@ -0,0 +1,366 @@
+<div align="center">
+
+**[English](README.en.md)** · [简体中文](README.md)
+
+# TaiyiForge
+
+**Turn six AI engineering standards into a single executable nine-stage R&D workflow**
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+[![Node](https://img.shields.io/badge/node-%3E%3D20-brightgreen)](package.json)
+[![npm version](https://img.shields.io/npm/v/oh-my-taiyiforge.svg)](https://www.npmjs.com/package/oh-my-taiyiforge)
+[![npm downloads](https://img.shields.io/npm/dm/oh-my-taiyiforge.svg)](https://www.npmjs.com/package/oh-my-taiyiforge)
+[![Version](https://img.shields.io/badge/version-0.40.0-orange)](CHANGELOG.md)
+[![v28 canonical](https://img.shields.io/badge/v28-28%20slashes%20%C2%B7%206%20umbrellas-blue)](docs/taiyi/canonical-commands.md)
+[![CI](https://img.shields.io/github/actions/workflow/status/Dong90/oh-my-taiyiforge/ci.yml?branch=main&label=CI)](https://github.com/Dong90/oh-my-taiyiforge/actions/workflows/ci.yml)
+[![Platforms](https://img.shields.io/badge/platforms-OpenCode%20%7C%20Claude%20%7C%20Codex%20%7C%20Cursor-8a2be2)](docs/QUICKSTART.md)
+
+**Document-driven AI R&D with gates, not vibes.**
+
+> Stop memorizing the phase order. Say `/taiyi:new` and the engine tells you what's next.
+
+[Quick Start](#quick-start) · [Usage Guide](docs/USAGE.md) · [Architecture](docs/ARCHITECTURE.md) · [Command Reference](docs/taiyi/canonical-commands.md) · [Full Flow](docs/taiyi/full-oss-flow.md) · [Contributing](CONTRIBUTING.md)
+
+<br />
+
+![TaiyiForge Architecture — Six standards × Workflow engine × Nine stages × Skill universe × Three-layer gates](docs/diagrams/visual/taiyiforge-architecture-ai-v023-full-4k-en-v2.png)
+
+</div>
+
+---
+
+## 1 · The Problem
+
+![Real terminal demo](docs/diagrams/demo.gif)
+
+<sub>27-second real terminal recording · <a href="docs/diagrams/demo.cast">asciicast source</a> (playable on <a href="https://asciinema.org">asciinema.org</a> or locally with `asciinema play docs/diagrams/demo.cast`)</sub>
+
+Every team using AI for serious work has hit some version of these:
+
+| Pain you've hit | Why it bites |
+|-----------------|--------------|
+| Agent forgets the phase order mid-task and jumps to code | Lost context, half-baked designs, untested changes — review has to redo the work |
+| Context explodes mid-change, requirements / design / code all lost | Long sessions die; resume from chat is impossible |
+| Each of OpenCode / Claude / Codex / Cursor has its own ad-hoc flow | Same feature, four different rituals — onboarding is per-tool, not per-team |
+| Even a typo fix has to go through nine stages | Rigid pipelines kill momentum on small fixes |
+| Don't dare let AI decide at critical nodes | "Looks good" review without a human sign-off is gambling with prod |
+| Don't know what the installed Skills are actually doing | Drift between docs and installed behavior, no audit trail |
+| Want to coexist with OMC / OMX | Lock-in to one orchestrator stack kills composability |
+
+TaiyiForge's answer to every one of these is in [§2 The Solution](#2--the-solution).
+
+---
+
+## 2 · The Solution
+
+A **single nine-stage artifact contract** + **28 v28 slashes + 6 umbrellas** + **one
+`/taiyi:*` vocabulary** that works the same on all four AI harnesses.
+
+> **v28 = recommended naming + top-bar convergence. IDE menus trimmed to 28 entries (v0.24). Set `TAIYI_FORGE_ALL_PROMPTS=1` to restore the full set. See [canonical-commands.md](docs/taiyi/canonical-commands.md).**
+
+TaiyiForge does not invent standards — it **orchestrates Harness · OpenSpec · GStack ·
+Superpowers · OMO · Spec-Kit into one state machine**. Use what you have installed;
+everything else is auto-skipped as optional.
+
+### 2.1 · The Nine-Stage Workflow
+
+One change = one slug, sequential execution, fixed artifacts. **Human gates** require
+`--approver` before the engine lets you pass.
+
+| # | Phase | Category | Skill | Artifact | Notes |
+|---|-------|----------|-------|----------|-------|
+| 1 | change | Human gate | `taiyi-change` | `CHANGE.md` | 3-5 paragraph proposal with scope |
+| 2 | requirement | Auto | `taiyi-requirement` | `REQUIREMENT.md` | Acceptance criteria + AC checkbox |
+| 3 | design | Human gate | `taiyi-design` | `DESIGN.md` | ≥2 options compared + decision |
+| 4 | ui-design | Auto | `taiyi-ui-design` | `UI-DESIGN.md` | Only for changes that touch UI |
+| 5 | task | Auto | `taiyi-task` | `TASK.md` | Slice into independently-PR-able pieces |
+| 6 | dev | Auto | `taiyi-dev` | TDD test + minimal impl | **TDD forced** — red first, then green |
+| 7 | test | Auto | `taiyi-test` | `TEST.md` | Summary kept; E2E runs in CI |
+| 8 | review | Human gate | `taiyi-review` | `REVIEW.md` | Cross-AI review + high-severity must-fix |
+| 9 | integration | Auto | `taiyi-integration` | `CHANGELOG.md` merged | Delivery gate: `audit` + `deliveryVerifyCmd` |
+| — | archive | Cleanup | `taiyi-integration` | `.taiyi/archive/` | Only after all nine stages pass |
+
+Full command list → **[canonical-commands.md](docs/taiyi/canonical-commands.md)** · Artifact layout → **[artifact-layout.md](docs/taiyi/artifact-layout.md)**
+
+### 2.2 · v28 Slash Catalog (28)
+
+Source of truth: [canonical-commands.md](docs/taiyi/canonical-commands.md) →
+`canonical_v28`. Legacy slashes still work, see [Legacy compatibility](#23--legacy-compatibility).
+
+| # | Group | Slash | Purpose |
+|---|------|------|---------|
+| 1–6 | Main chain | `new` · `status` · `write` · `continue` · `apply` · `archive` | Daily shortest path |
+| 7–10 | Session | `pause` · `resume` · `cancel` · `list` | Cross-session |
+| 11–13 | Diagnose | `doctor` · `audit` · `verify` | Self-check + delivery gate |
+| 14–17 | Delivery | `commit` · `ship` · `land` · `release` | gstack delivery chain |
+| 18–19 | Routing | `gstack <skill>` · `sp <skill>` | External harness routing |
+| 20–22 | Stage shortcuts | `explore` · `tdd plan\|dev` · `flow` | Skip the nine-stage |
+| 23–28 | **Umbrellas (6)** | `token …` · `test …` · `review …` · `diagram …` · `mode …` · `workflow …` | Domain multi-subcommand |
+
+**Daily shortest path**:
+
+```text
+/taiyi:new → /taiyi:write → /taiyi:continue → /taiyi:apply → … → /taiyi:commit → /taiyi:continue integration → /taiyi:archive
+```
+
+**Umbrella quick map** (full map in [canonical-commands.md §伞形命令·子命令地图](docs/taiyi/canonical-commands.md)):
+
+| Umbrella | Sub-commands | Count |
+|----------|--------------|------:|
+| `/taiyi:token` | `status` · `record` · `scan` · `compress` | 4 |
+| `/taiyi:test` | `smoke` · `e2e` · `qa` · `ui` · `security` | 5 |
+| `/taiyi:review` | `loop` · `check` · `health` · `gstack` | 4 |
+| `/taiyi:diagram` | `pipeline` · `c4` · `arch` · `render` · `flow` | 5 |
+| `/taiyi:mode` | `ralph` · `autopilot` · `daemon` · `team` · `ultrawork` · `agent` · `step` · `stop` · `list` · `keyword` · `preflight` | 11 |
+| `/taiyi:workflow` | `plan` · `ralplan` · `loop` · `check` · `run` · `sync` · `ccg` · `sciomc` · `deepinit` · `remember` · `ultraqa` | 11 |
+
+### 2.3 · Legacy compatibility
+
+Legacy slashes & CLI **still work** — listed in
+[canonical-commands.md §Legacy 兼容](docs/taiyi/canonical-commands.md). Don't add new
+top-bar duplicates of v28 umbrellas.
+
+| Legacy | v28 now |
+|--------|---------|
+| `/taiyi:pause` | `/taiyi:pause` |
+| `/taiyi:state` · `/taiyi:state-read` | `/taiyi:status` |
+| `/taiyi:next` · `/taiyi:done` | `/taiyi:status` + `/taiyi:continue` |
+| `/taiyi:change` … `/taiyi:integration` | `/taiyi:write` |
+| `/taiyi:ralph` etc. OMC | `/taiyi:mode ralph` |
+| `npx taiyi new` · `npx taiyi walkthrough` | `/taiyi:new` · `/taiyi:flow help` |
+
+---
+
+## 3 · The Evidence
+
+### 3.1 · One Skill Set, Four Harnesses
+
+One `node scripts/taiyi-forge.sh install --all` syncs to all four harnesses; missing
+ones are auto-skipped. Same 28 v28 top-bar slashes, same `taiyi-*` Skills — different
+chat syntax & MCP surface per harness:
+
+| Harness | Chat entry | Engine entry | MCP | Hook / keyword | Read more |
+|---------|-----------|-------------|-----|----------------|-----------|
+| **Claude Code** | `/taiyi:new … /taiyi:archive` + Skill + `~/.claude/commands/taiyi-*.md` | Agent Bash | `taiyi_doctor` · `taiyi_audit` | keyword hook | [control-plane.md §四端对照](docs/taiyi/control-plane.md) |
+| **Codex** | `$taiyi-new` … `$taiyi-archive` (`prompts/taiyi-*.md` — **not** `/taiyi:*`) | Agent runs `scripts/taiyi-forge.sh` | None (shell) | `codex-keyword-preflight.mjs` + `developer_instructions` (`~/.codex/config.toml`) | [control-plane.md §Codex](docs/taiyi/control-plane.md) |
+| **Cursor** | `/taiyi:new … /taiyi:status` + `taiyiforge.mdc` rule + `~/.cursor/commands/taiyi-*.md` | Agent terminal / MCP | `taiyi_doctor` · `taiyi_audit` | keyword hook | [mcp-setup.md](docs/taiyi/mcp-setup.md) |
+| **OpenCode** | `taiyi_new` / `taiyi_*` plugin tools + `~/.config/opencode/commands/taiyi-*.md` | plugin + `/taiyi-*` slashes | (plugin built-in) | plugin-managed | [control-plane.md §OpenCode](docs/taiyi/control-plane.md) |
+
+> **Codex note**: chat entry is the `$taiyi-*` keyword (not `/taiyi:*`), routed via
+> `codex-keyword-preflight.mjs` and `developer_instructions`. See
+> [control-plane.md](docs/taiyi/control-plane.md).
+
+### 3.2 · Chat Track vs Engine Track
+
+| Surface | Used by | Does what | Example |
+|---------|---------|-----------|---------|
+| **Chat slash** | Developer / Agent | Write artifact, run TDD, load specialized Skill | `/taiyi:write` · `/taiyi:apply` · `/taiyi:tdd dev` |
+| **Engine CLI** | Agent / CI (run **for** you) | Validate artifact, gates, advance phase | `npx taiyi continue <slug>` · `npx taiyi complete <slug> change --approver "…"` |
+| **Shell entry** | Agent / CI | Equivalent to CLI; written into consumer project after install | `scripts/taiyi-forge.sh status --json --compact` |
+| **MCP** | Cursor etc. | Read-only troubleshooting | `taiyi_doctor` · `taiyi_audit` |
+
+**Principle**: Users only say `/taiyi:*`; **never** make the user type
+`taiyi-forge.sh` by hand. Agents read `status --json --compact` `engineTruth`;
+never dump full artifacts into chat.
+
+### 3.3 · Architecture at a Glance
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│  Entry: taiyi CLI · taiyi-forge.sh · OpenCode plugin · MCP    │
+└───────────────────────────┬─────────────────────────────────┘
+                            ▼
+┌─────────────────────────────────────────────────────────────┐
+│  workflow-engine — intent analysis · token budget · routing · gates │
+└───────────────────────────┬─────────────────────────────────┘
+                            ▼
+┌─────────────────────────────────────────────────────────────┐
+│  .taiyi/changes/<slug>/  — CHANGE … CHANGELOG (source of truth)  │
+└─────────────────────────────────────────────────────────────┘
+         chat loads taiyi-* Skill to write artifacts ↑   ↓ engine validates & advances phase
+```
+
+- Code layout → **[docs/ARCHITECTURE.md](docs/ARCHITECTURE.md)**
+- C4 source → **[docs/c4/](docs/c4/)**
+- Visual poster (top of README) → [docs/diagrams/visual/](docs/diagrams/visual/)
+
+---
+
+## 4 · Quick Start
+
+> **Zero-build install**: v0.24.0+ supports `npx taiyi-forge-install --all` one-liner to all four harnesses without cloning the repo. Source install still available.
+>
+> **v0.25.0 GitHub install**: v0.25.x is not yet on npm (24h name reclaim lock after upstream unpublish). Install directly from the GitHub tag — see [Option A0](#option-a0--install-directly-from-github-new-in-v025-when-npm-is-unavailable).
+
+### Option A0 · Install directly from GitHub (new in v0.25, when npm is unavailable)
+
+```bash
+# Install from a GitHub tag into your project (works in any consumer repo, no npm required)
+# MUST use the git+ prefix — that makes npm clone the repo and run postinstall (npm run build)
+npm install 'git+https://github.com/Dong90/oh-my-taiyiforge.git#v0.25.0'
+# Or install globally and run bin via npx
+npm install -g 'git+https://github.com/Dong90/oh-my-taiyiforge.git#v0.25.0'
+npx -p 'git+https://github.com/Dong90/oh-my-taiyiforge.git#v0.25.0' taiyi-forge-install --all
+```
+
+> The `git+` prefix is required (tarball URLs skip postinstall, so dist/ won't get built and bins will fail). Pin to a tag (`#v0.25.0`, `#v0.25.1`), branch (`#main`), or commit SHA.
+
+### Option A · One-liner install (recommended, v0.24+)
+
+```bash
+npx taiyi-forge-install --all          # One-shot to all four harnesses + optional deps
+npx taiyi-forge-install --cursor       # Cursor only
+npx taiyi-forge-install --claude --opencode
+
+# Install all prompts (default is v28 28 top-bar entries only):
+TAIYI_FORGE_ALL_PROMPTS=1 npx taiyi-forge-install --all
+```
+
+### Option B · Source install
+
+```bash
+git clone https://github.com/Dong90/oh-my-taiyiforge.git
+cd oh-my-taiyiforge
+npm install && npm run build && npm test
+node scripts/taiyi-forge.sh install --all
+```
+
+### Option C · Run the example projects (zero-install quick feel)
+
+```bash
+cd examples/commands-smoke
+npm install
+npm run chat-demo          # Chat verbs: new / status / check / continue
+npm run walkthrough-e2e    # Nine-stage shell E2E + iron-triangle
+# /taiyi:doctor           # Workspace + install self-check (chat slash)
+```
+
+| Example | Purpose |
+|---------|---------|
+| [examples/full-flow-demo](examples/full-flow-demo/README.md) | Nine-stage + slash E2E |
+| [examples/commands-smoke](examples/commands-smoke/) | Command smoke tests |
+| [examples/browser-e2e-smoke](examples/browser-e2e-smoke/) | CI templates |
+| [examples/verification-suite](examples/verification-suite/) | Minimal integration demo |
+
+> Want `npm install oh-my-taiyiforge`? For v0.25 install from GitHub for now (see [Option A0](#option-a0--install-directly-from-github-new-in-v025-when-npm-is-unavailable)). `npm i oh-my-taiyiforge` will resume once we re-publish to npm.
+
+### Option D · Your first change (5 minutes)
+
+```bash
+# Recommended entry: auto-slug + engine guidance
+npx taiyi walkthrough
+npx taiyi init-wizard               # interactive config initialization
+npx taiyi new "Add login optimization"  # writes to .taiyi/changes/<slug>/
+npx taiyi status                         # current phase + recommended Skill + next step
+npx taiyi import <branch>               # import from git branch (reads commits, generates CHANGE.md)
+
+# Edit .taiyi/changes/<slug>/CHANGE.md, then:
+npx taiyi complete <slug> change --approver "your-name"   # human gate
+npx taiyi continue <slug>                                 # auto gate
+
+# In chat (OpenCode / Claude / Cursor — Codex uses `$taiyi-*` keywords instead):
+/taiyi:new "<feature title>"              # lay CHANGE.md template
+/taiyi:status                             # current phase + recommended Skill + next step
+/taiyi:write                              # write current phase artifact (handles 9 stages)
+/taiyi:continue --approver "your-name"    # human gate (change / design / review)
+/taiyi:apply                              # dev/test harness checklist
+/taiyi:commit                             # post-dev commit with Taiyi-Change trailer
+/taiyi:archive                            # archive after all nine stages
+
+# Common umbrella picks:
+/taiyi:doctor                             # install + workspace self-check
+/taiyi:token compress <slug>              # long-session → CONTEXT-COMPACT.md
+/taiyi:test smoke                         # Playwright built-in smoke
+/taiyi:flow bug <slug>                    # lite path for small fixes
+```
+
+That's it. **Phase order, artifact templates, gate validation are the engine's job**.
+You write Markdown and code.
+
+Agent-priority troubleshooting:
+
+```bash
+scripts/taiyi-forge.sh doctor --json --compact
+scripts/taiyi-forge.sh audit --json --compact
+```
+
+---
+
+## 5 · Reference
+
+### 5.1 · Documentation
+
+| Document | What it covers | When to read |
+|----------|---------------|--------------|
+| [docs/QUICKSTART.md](docs/QUICKSTART.md) | 5-minute walkthrough | First install |
+| [docs/USAGE.md](docs/USAGE.md) | Scenarios · daily rhythm · delivery chain | After the walkthrough |
+| [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) | Architecture overview + code layout | Hacking the engine / debugging |
+| [docs/taiyi/canonical-commands.md](docs/taiyi/canonical-commands.md) | v28 slash command table | Looking up a command |
+| [docs/taiyi/control-plane.md](docs/taiyi/control-plane.md) | Agent discipline + token discipline | Onboarding an Agent |
+| [docs/taiyi/full-oss-flow.md](docs/taiyi/full-oss-flow.md) | Superpowers + all-plugins demo | Want a full end-to-end |
+| [docs/taiyi/integrations.md](docs/taiyi/integrations.md) | Iron triangle + plugin integrations | Installing optional pieces |
+| [AGENTS.md](AGENTS.md) | Agent's read-state entry point | Configuring Agents |
+| [CONTRIBUTING.md](CONTRIBUTING.md) | Contribution guide | Before opening a PR |
+| [CHANGELOG.md](CHANGELOG.md) | Release notes | Checking for updates |
+| [docs/diagrams/demo.gif](docs/diagrams/demo.gif) | Real terminal recording (27s) | Quick feel of the engine |
+| [README.md](README.md) | 简体中文版 | 中文用户 |
+
+### 5.2 · Development & Verification
+
+**Contributor clone:**
+
+```bash
+git clone https://github.com/Dong90/oh-my-taiyiforge.git
+cd oh-my-taiyiforge
+npm install && npm run build && npm test
+node scripts/taiyi-forge.sh install --all
+```
+
+**Common commands:**
+
+```bash
+npm test               # Vitest contracts + nine-stage E2E
+npm run test:watch     # watch mode
+npm run build          # TypeScript → dist/
+npm run dogfood        # root repo demo (eat your own dog food)
+npm run ci:platforms   # four-platform smoke (opencode/claude/codex/cursor)
+npm run check:docs     # doc-vs-commands.yaml sync check
+```
+
+CI: [`.github/workflows/ci.yml`](.github/workflows/ci.yml) — platform smoke runs across
+a 4 × ubuntu matrix.
+
+### 5.3 · Roadmap & Status
+
+| Version | Status | Key milestones |
+|---------|--------|----------------|
+| v0.23.0 | ✅ Released | **canonical v28**: 28 顶栏 slashes + 6 umbrellas (`token`/`test`/`review`/`diagram`/`mode`/`workflow`) + `skill-fusion-principles.md` + `validateV28CatalogSync` gate |
+| v0.24.0 | ✅ Released | First npm release · `npx taiyi-forge-install` zero-build install · README v28 convergence rewrite · IDE menu trimmed to 28 entries (umbrella Phase 2) |
+| v0.26.0 | ✅ Released | **Evidence gate**: acceptance criteria must carry `evidence{command,exitCode:0}` to prevent false passes · enforced commit trailers · status 5s debounce · profile expanded to 10 |
+| v0.27.0 | ✅ Released | **Event bus** + structured logger · CLI 62→18 diet (handlers map replacing giant switch) · milestone overview · schema expansion + 10 SKILL.md rewrites |
+| v0.30.0 | ✅ Released | **Data-driven Mermaid chain**: SSOT triple binding + rollback trace · `is_cli_only` skips UI-stage contract · ast-grep pitfalls (8 patterns) + `scan.sh` |
+| v0.35.0 | ✅ Released | **ChangeGraph knowledge graph**: load/edges/query/render — 49 tests · `PHASE-CONTEXT.md` graph-driven generation (replaces sequential upstream reads) |
+| v0.40.0 | ✅ Latest | review date binding + SSOT cross-refs · E2E fixtures extended 7 fields · graph context compression · CI/Playwright/vitest timeout fixes |
+| v1.0.0 | ⏳ Planned | Lock 9-stage API · 4-platform parity · external case-study collection |
+
+**Ready today**: full nine-stage pipeline · four-harness shared Skills · forced TDD ·
+evidence anti-fake-pass gate · token compression · ChangeGraph knowledge graph · platform-smoke CI · zero-build one-liner install (v0.24+)
+**Not yet**: production-grade SLA · full i18n
+
+### 5.4 · Community & Contributing
+
+- 🐛 **Report a bug**: [GitHub Issues](https://github.com/Dong90/oh-my-taiyiforge/issues/new) · `bug` label
+- 💡 **Idea / RFC**: [Discussions](https://github.com/Dong90/oh-my-taiyiforge/discussions)
+- 🔧 **Open a PR**: read [CONTRIBUTING.md](CONTRIBUTING.md) first; `npm test` + `npm run check:docs` must be green
+- ⭐ **Star / Watch**: drop a star to get notified on the next release
+- 🧵 **Codex users**: search for `$taiyi-*` keywords; four-harness entry decision tree in [docs/taiyi/invoke.yaml](docs/taiyi/invoke.yaml)
+
+Code of conduct: follow the [Contributor Covenant](https://www.contributor-covenant.org/) spirit — critique ideas, not people.
+
+### 5.5 · License
+
+[MIT](LICENSE) © 2026 TaiyiForge contributors
+
+### 5.6 · Acknowledgments
+
+Inspired by: [oh-my-claudecode](https://github.com/Yeachan-Heo/oh-my-claudecode) · [oh-my-codex](https://github.com/Yeachan-Heo/oh-my-codex) · Harness Engineering · OpenSpec · GStack · Superpowers · OMO · Spec-Kit.

package/README.md

@@ -0,0 +1,176 @@
+<div align="center">
+
+[English](README.en.md) · **简体中文**
+
+# TaiyiForge（太一炉）
+
+**把 AI 写代码的玄学，变成一条可执行、可审计的工程流水线。**
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+[![npm version](https://img.shields.io/npm/v/oh-my-taiyiforge.svg)](https://www.npmjs.com/package/oh-my-taiyiforge)
+[![CI](https://img.shields.io/github/actions/workflow/status/Dong90/oh-my-taiyiforge/ci.yml?branch=main&label=CI)](https://github.com/Dong90/oh-my-taiyiforge/actions/workflows/ci.yml)
+[![Platforms](https://img.shields.io/badge/platforms-OpenCode%20%7C%20Claude%20%7C%20Codex%20%7C%20Cursor-8a2be2)](docs/QUICKSTART.md)
+
+</div>
+
+![TaiyiForge 架构](docs/diagrams/visual/taiyiforge-architecture-ai-v023-full-4k-zh-v2-fix.png)
+
+[快速开始](#快速开始) · [核心能力](#核心能力) · [文档](#文档) · [社区](#社区)
+
+---
+
+## 为什么需要 TaiyiForge？
+
+用 AI 写代码很简单。用 AI 做工程很难。
+
+| 你遇到的问题 | 根因 |
+|---------|---------|
+| Agent 跳过需求/设计，直接写代码 | 没有阶段约束，AI 总会走捷径 |
+| 长会话上下文爆炸，之前写的全丢了 | 没有 token 管理机制，上下文就是消耗品 |
+| Claude / Codex / Cursor 各一套流程 | 同一特性四套仪式，按工具入职不按团队 |
+| 没人敢让 AI 独立拍板 | 没有门控的 review 形同虚设 |
+| 装好的 Skill 实际行为没人说得清 | 文档漂移，出问题没法追溯 |
+
+**TaiyiForge 的回答**：一套九阶段工件契约 + 状态机引擎。在四套 AI 终端里行为完全一致。
+
+> `/taiyi:new` → 引擎告诉你下一步。不用背阶段顺序，不用记工件模板。
+
+---
+
+## 演示
+
+27 秒终端实录。从零创建一个 change，引擎自动推进阶段：
+
+![终端演示](docs/diagrams/demo.gif)
+
+<sub>注：`/taiyi:new` → `/taiyi:status` → `/taiyi:write` → `/taiyi:continue`，四步走完一个阶段。</sub>
+
+---
+
+## 快速开始
+
+```bash
+# 1. 安装
+npm install oh-my-taiyiforge
+
+# 2. 同步 Skill 到你的 AI 终端（Claude / Cursor / OpenCode / Codex）
+npx taiyi-forge-install --all
+
+# 3. 在聊天里创建第一个 change
+/taiyi:new "优化登录流程"
+/taiyi:status
+```
+
+**你只管写 Markdown 和代码。阶段顺序、工件模板、门控校验全是引擎的活。**
+
+```bash
+# 只装某一端
+npx taiyi-forge-install --cursor
+npx taiyi-forge-install --claude --opencode
+
+# 源码安装
+git clone https://github.com/Dong90/oh-my-taiyiforge.git
+cd oh-my-taiyiforge && npm install && npm run build
+node scripts/taiyi-forge.sh install --all
+```
+
+[详细安装 →](docs/QUICKSTART.md)
+
+---
+
+## 核心能力
+
+### 九阶段流水线
+
+每次变更顺序走九步，每步固定产出。关键节点 **人类门控**——AI 不能放行自己。
+
+```
+change → requirement → design → ui-design → task → dev → test → review → integration
+   ↑人类审批            ↑人类审批                                   ↑人类审批
+```
+
+| 阶段 | 产出 | 拍板 |
+|------|------|------|
+| change | 方案 + 范围边界 | **人** |
+| requirement | 验收标准 + AC | 引擎 |
+| design | ≥2 方案对比 + 决策 | **人** |
+| ui-design | UI/UX 契约 | 引擎（仅触 UI 时） |
+| task | 可独立 PR 的片段 | 引擎 |
+| dev | TDD 先红后绿 | 引擎 |
+| test | 测试证据摘要 | 引擎 |
+| review | 跨 AI 评审 | **人** |
+| integration | 交付门控 | 引擎 |
+
+[完整流程 →](docs/taiyi/full-oss-flow.md)
+
+### 一套命令，四端通用
+
+不管是 Claude Code 的 `/taiyi:new`、Cursor 的同名 slash、Codex 的 `$taiyi-new`，还是 OpenCode 的插件工具——**同一套词汇，同一种行为**。
+
+| 版本 | 状态 | 关键里程碑 |
+|------|------|----------|
+| v0.23.0 | ✅ 已发布 | **canonical v28**: 28 顶栏 slashes + 6 umbrellas(`token`/`test`/`review`/`diagram`/`mode`/`workflow`) + `skill-fusion-principles.md` + `validateV28CatalogSync` gate |
+| v0.24.0 | ✅ 已发布 | 首次 npm 发布 · `npx taiyi-forge-install` 零构建安装 · README v28 收敛重写 · IDE 菜单裁剪为 28 条（umbrella Phase 2） |
+| v0.26.0 | ✅ 已发布 | **evidence 强校验**: AC 必配 `evidence{command,exitCode:0}` 防假过门 · commit trailer 强制执行 · status 5s 防抖 · profile 扩容 10 种 |
+| v0.27.0 | ✅ 已发布 | **event bus** + structured logger · CLI 62→18 瘦身（handlers map 替代巨型 switch）· TODO 里程碑总览 · schema 扩展 + 10 个 SKILL.md 重写 |
+| v0.30.0 | ✅ 已发布 | **data-driven Mermaid chain**: 设计图 SSOT 三源绑定 + rollback 追溯 · `is_cli_only` 跳过 UI 阶段契约 · ast-grep 陷阱规则(8 patterns) + `scan.sh` |
+| v0.35.0 | ✅ 已发布 | **ChangeGraph 知识图谱**: load/edges/query/render — 49 tests · `PHASE-CONTEXT.md` 图谱驱动生成（替代逐份读上游工件） |
+| v0.40.0 | ✅ 最新 | review 日绑定 + SSOT 交叉引用 · E2E fixtures 扩 7 字段 · graph 上下文压缩 · 平台冒烟 CI / Playwright / vitest 超时修复 |
+| v1.0.0 | ⏳ 计划 | 锁定 9 阶段 API · 四端 parity · 外部案例收集 |
+
+**已就绪**: 完整九阶段流水线 · 四端共享 Skill · 强制 TDD · evidence 防假过门 · token 压缩 · ChangeGraph 知识图谱 · 平台冒烟 CI · 零构建一行安装(v0.24+)
+**未就绪**: 生产级 SLA · 完整 i18n
+
+### 不止流水线
+
+- **强制 TDD**：dev 阶段先红后绿，不是建议是硬约束
+- **evidence 防假过门**：每个 AC 必须配可执行验证命令，跑不过不放
+- **token 压缩**：长会话自动产出 `CONTEXT-COMPACT.md`，跨天无缝续上
+- **ChangeGraph**：自动追踪变更间依赖，改一处知全局
+- **不搞一刀切**：大功能 `full`，小修复 `lite`，typo 改 `nano`
+
+---
+
+## 对比
+
+| | 直接跟 AI 对话 | TaiyiForge |
+|---|---|---|
+| 流程约束 | 靠 prompt 和记忆祈祷 | 状态机强制推进 |
+| 人类审批 | 看心情，容易跳过 | `--approver` 硬拦，不批不放 |
+| 多工具一致性 | 换工具换流程 | 同一套 Skill |
+| 上下文持久 | 丢了重新聊 | token 压缩 + 断点续传 |
+| 灵活度 | 全靠自觉 | 10 种 profile，按需选择 |
+
+---
+
+## 文档
+
+| 文档 | 内容 | 什么时候读 |
+|------|------|-----------|
+| [QUICKSTART](docs/QUICKSTART.md) | 5 分钟走通全流程 | 第一次用 |
+| [USAGE](docs/USAGE.md) | 日常节奏、场景、交付链 | 跑通之后 |
+| [ARCHITECTURE](docs/ARCHITECTURE.md) | 系统架构 + 代码布局 | 想改引擎 |
+| [canonical-commands](docs/taiyi/canonical-commands.md) | 28 条 slack 命令表 | 查命令 |
+| [control-plane](docs/taiyi/control-plane.md) | Agent 纪律 + token 纪律 | 给 Agent 配 onboarding |
+| [full-oss-flow](docs/taiyi/full-oss-flow.md) | Superpowers + 全插件端到端 | 想看完整流程 |
+| [CONTRIBUTING](CONTRIBUTING.md) | 贡献指南 | 开 PR 之前 |
+| [CHANGELOG](CHANGELOG.md) | 发布说明 | 查更新 |
+
+---
+
+## 社区
+
+- 🐛 [报告 Bug](https://github.com/Dong90/oh-my-taiyiforge/issues/new?labels=bug)
+- 💡 [想法 & 讨论](https://github.com/Dong90/oh-my-taiyiforge/discussions)
+- 🔧 [贡献代码](CONTRIBUTING.md) — `npm test` 必须绿
+- ⭐ **Star 一下，下次发布不迷路**
+
+TaiyiForge 不发明新标准——它把 **Harness · OpenSpec · GStack · Superpowers · OMO · Spec-Kit** 编排成一台状态机。装了什么用什么，其余自动跳过。
+
+---
+
+## 许可证
+
+[MIT](LICENSE) © 2026 TaiyiForge contributors
+
+灵感来源：[oh-my-claudecode](https://github.com/Yeachan-Heo/oh-my-claudecode) · [oh-my-codex](https://github.com/Yeachan-Heo/oh-my-codex) · Harness Engineering · OpenSpec · GStack · Superpowers · OMO · Spec-Kit

package/dist/cli/install-cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli/install-cli.js

@@ -0,0 +1,4 @@
+#!/usr/bin/env node
+import { runInstallCli } from "../install/run.js";
+const code = await runInstallCli(process.argv.slice(2));
+process.exit(code);

package/dist/cli/taiyi.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};