yibi-stack

yibi-stack

English | 繁體中文

---

English

What is yibi-stack?

yibi-stack is a Claude Code skill and plugin stack for engineering teams who use Claude as their primary development tool. It transforms Claude Code from a capable-but-undisciplined assistant into a workflow-aware engineering partner with built-in guardrails.

The stack ships in two layers:

• Plugins (plugins/) — installable via claude plugin install, add hooks and skills that activate automatically in every session
• Skills (skills/) — SKILL.md runbooks that tell Claude how to approach specific tasks (TDD, PR review, spec writing, release workflow)

Why yibi-stack?

Without guardrails, Claude Code tends to:

• Write bash commands that trigger Claude Code's internal confirmation dialogs (nested quotes, stateful cd, inline multi-language)
• Generate specs too shallow to build from
• Lose work context when conversations compress
• Skip test discipline under time pressure

yibi-stack layers three forms of enforcement on top of Claude Code:

1. Automated hooks — catch problems before execution, not after
2. Methodology skills — runbooks that embed spec-writing, test-design, and review discipline into Claude's workflow (test-first is enforced by the PR cycle's red-first gate, not a skill)
3. Persistent tooling — mycelium, scheduler, and port registry that survive across conversations

Benefits

Benefit	Mechanism
Safer shell execution	harness plugin intercepts 3 anti-pattern categories (AP1: overcomplex single commands / AP2: unicode in shell strings / AP3: stateful cd) via PreToolUse hooks — before they cause silent failures
Spec-first development	sdd plugin + spectra-amplifier skill expands thin requirements into 5-layer specs (Context → Behavior → Data → Constraints → Acceptance Criteria), compatible with OpenSpec change management
Multi-model PR review	pr-cycle-deep orchestrates Claude + Codex + Gemini in parallel independent review → cross-model debate → aggregate, catching issues no single model would flag
Persistent work memory	mycelium skill auto-handovers before context compression and restores on next session start — no more losing track of multi-day work
Release discipline	bump-version, protect-push, and ci-triage skills codify release workflow so Claude doesn't push to main without explicit intent
Test methodology	pr-cycle-deep Step 1.7 red-first gate — when the repo provides scripts/red-first-check.py (otherwise reported as unchecked — not a pass, shown to the human; yibi-stack itself ships none), feat/fix tests must fail against the base production code and refactor/perf tests must still pass — plus qa-test-design (6 test design techniques)

Architecture

plugins/          Claude Code plugin packs (installable via claude plugin install)
  harness/        Harness readiness eval + PreToolUse hook enforcement + anti-pattern guide
  sdd/            Spec-Driven Development: Spectra + OpenSpec methodology
  growth/         Knowledge extraction: mycelium, learn, PR retro/control log, CLAUDE.md prune
  dev-cycle/      Development flow: PR cycles, CI triage, setup/handover, local port manager, debug
  3rd-tools/      Third-party AI: Codex, Antigravity CLI (agy/Gemini), model verification
  methodology/    Portable event-storming, problem-frames, QA test design methodology

skills/           Agent execution layer -- SKILL.md runbooks (installed via make install)
  <skill-name>/   Each skill is a flat directory with a SKILL.md runbook (or a symlink)
                  scope:global  -- works in any repo (methodology, cross-project tools)
                  scope:project -- requires this repo's Python tasks

tasks/            Python implementation (CLI, service, models, SQLite DB)
commands/         Claude Code slash commands (symlinked to ~/.claude/commands/)
scripts/          CI and lint tooling

Plugins vs Skills — what's the difference?

Plugins (plugins/harness, plugins/sdd, plugins/growth, plugins/dev-cycle, plugins/3rd-tools, plugins/methodology) are proper Claude Code plugins with package.json manifests. They install hooks, rules, and bundled skills. Installable via claude plugin install without cloning.

Skills (skills/*/SKILL.md) are runbook files — not plugins. They're installed as symlinks into ~/.claude/skills/ via make install. They tell Claude how to approach a workflow; no hooks are involved. Skills are not individually installable via claude plugin install.

Install

The two user installation tracks are complementary: Track 1 installs the Claude Code layer, while Track 2 installs the Python CLIs required by tasks-backed skills.

Track 1 — Claude Code plugins

Use this track for the skills, commands, rules, and hooks bundled in each plugin. It is lightweight and does not require a clone.

claude plugin marketplace add heyu-ai/yibi-stack
claude plugin install harness@yibi-stack
claude plugin install sdd@yibi-stack
claude plugin install growth@yibi-stack
claude plugin install dev-cycle@yibi-stack
claude plugin install methodology@yibi-stack

Track 2 — tasks-backed CLI tools

Use this track to install the mycelium, pr-orchestrator, and portman console scripts consumed by tasks-backed skills:

uv tool install "yibi-stack @ git+https://github.com/heyu-ai/yibi-stack@v1.23.2"

Track 2 is required by these six skills, grouped by their plugin pack:

• growth: pr-control-log, pr-retrospective, mycelium, and learn
• dev-cycle: pr-cycle-fast and local-port-manager

Without Track 2, those skills fail loud before doing any work and show the same command above as the install hint.

Developer/contributor path — local checkout

Use a local checkout when developing or contributing to yibi-stack, or when installing repo-managed skills, hooks, and the scheduler. This path is separate from the two user tracks above. Tasks-backed harness skills still require the checkout setup below for their Python implementation.

# 1. Install plugins (pre-execution hooks + rules)
claude plugin marketplace add heyu-ai/yibi-stack
claude plugin install harness@yibi-stack sdd@yibi-stack growth@yibi-stack dev-cycle@yibi-stack methodology@yibi-stack

# 2. Clone and install skills + hooks + scheduler
git clone https://github.com/heyu-ai/yibi-stack
cd yibi-stack
make install-all

Verify install status (shows only this repo's skills, excludes gstack/external):

make status-own

Key Skills

Skill	What it does
spectra-amplifier	5-layer spec expansion via sdd plugin
pr-review-cycle	Full PR lifecycle: create -> parallel review (4 subagents) -> fix -> CI -> merge
pr-cycle-fast	Fast lifecycle orchestrator: Python state machine, 1 reviewer, resumable
pr-cycle-deep	Deep lifecycle: mob review (Claude + Codex + Gemini) + SDD amplifier-verifier
bash-anti-patterns	AP1/AP2/AP3 detection guide + shell quoting hygiene reference
qa-test-design	6 test design techniques (equivalence, boundary, decision table...)
mycelium	Cross-session work handover and insight collection
bump-version	Version bump (Flutter/Python/Node/Go) + CHANGELOG + git tag
protect-push	Hook to prevent accidental pushes from worktree branches to main
ci-triage	CI failure triage funnel (Lint -> Type -> Security -> Tests)
learn	Browse, search, prune, and export lessons learned
pr-retrospective	5-question PR retro, routes lessons to .claude/rules/ or CLAUDE.md
claude-md-prune	Prune CLAUDE.md bloat: route gotchas to .claude/rules/ files, stay under 200-line soft cap
agy	Antigravity CLI (Gemini) second opinion: lightweight single-model review / challenge mode
harness-eval	11-dimension harness readiness assessment with PASS/WARN/FAIL checklist and priority TODO

See skills/README.md for the full index.

Plugins

Plugin	Install	Description
harness	claude plugin install harness@yibi-stack	Harness readiness evaluation, pre-execution bash anti-pattern detection, worktree push protection, and fleet usage burn-rate guarding.
sdd	claude plugin install sdd@yibi-stack	Spectra + OpenSpec spec-amplifier methodology
growth	claude plugin install growth@yibi-stack	Knowledge extraction and retention: mycelium, learn, PR retro/control log, CLAUDE.md prune
dev-cycle	claude plugin install dev-cycle@yibi-stack	Development workflow: PR cycles, CI triage, setup/handover, local port manager, debug
3rd-tools	claude plugin install 3rd-tools@yibi-stack	Codex, Antigravity CLI (agy/Gemini), model verification
methodology	claude plugin install methodology@yibi-stack	Portable methodology: event storming, problem frames, QA test design.

---

繁體中文

yibi-stack 是什麼？

yibi-stack 是一套專為以 Claude Code 作為主力開發工具的工程師設計的 skill 與 plugin 集。它讓 Claude Code 從一個能力強但缺乏紀律的助手，升級為有工作流程意識、有自我約束力的工程夥伴。

這個 stack 分兩層：

• Plugins（plugins/）— 透過 claude plugin install 安裝，每次 session 自動啟用 hook 與 skill
• Skills（skills/）— SKILL.md runbook，告訴 Claude 如何處理特定任務（TDD、PR review、規格撰寫、發版流程）

為什麼需要 yibi-stack？

沒有護欄的 Claude Code 容易出現這些問題：

• 寫出觸發 Claude Code 確認框的 bash 指令（巢狀引號、stateful cd、內嵌多語言）
• 產生粒度太粗、無法直接實作的規格
• 對話壓縮後遺失工作脈絡
• 在時間壓力下跳過測試紀律

yibi-stack 在 Claude Code 之上疊加三層約束：

1. 自動化 hook — 在執行前攔截問題，而不是事後除錯
2. 方法論 skill — 把規格撰寫、測試設計、PR 審閱的紀律嵌入 Claude 的工作流程（先寫測試由 PR 流程的 red-first gate 執行，不是靠 skill）
3. 持久化工具 — 跨對話的 session 記憶、定期排程器、port 登記表

主要好處

好處	機制
更安全的 shell 執行	harness plugin 透過 PreToolUse hook，在執行前攔截三類反模式（AP1 過複雜單行 / AP2 bash 字串 Unicode / AP3 stateful cd），避免靜默失敗
規格先行的開發	sdd plugin + spectra-amplifier skill 把薄需求展開為五層規格（情境→行為→資料→約束→驗收條件），兼容 OpenSpec 變更管理框架
多模型 PR 審閱	pr-cycle-deep 讓 Claude + Codex + Gemini 並行獨立審閱再交叉辯論，捕捉單一模型漏掉的問題
持久化工作記憶	mycelium skill 在對話壓縮前自動交班，下次 session 開啟時自動恢復工作上下文，多日開發不斷線
發版紀律	bump-version + protect-push + ci-triage 讓 Claude 不會在沒有明確意圖的情況下推上 main
測試方法論	pr-cycle-deep Step 1.7 的 red-first gate：repo 有提供 scripts/red-first-check.py 時才執行（沒有就回報 unchecked：不是通過，交給人確認；yibi-stack 本身沒有附），feat／fix 的測試在 base 產品碼上必須失敗、refactor／perf 必須仍通過；另有 qa-test-design（六大測試設計技術）

架構

plugins/          Claude Code plugin packs（可透過 claude plugin install 安裝）
  harness/        Harness 就緒度評量 + PreToolUse hook 防線 + 反模式修法指南
  sdd/            Spec-Driven Development：Spectra + OpenSpec 方法論
  growth/         知識萃取與留存：mycelium、learn、PR 回顧／審計、CLAUDE.md 精簡
  dev-cycle/      開發流程：PR cycles、CI 診斷、工作區設定／交班、本機 port 管理、debug
  3rd-tools/      第三方 AI：Codex、Antigravity CLI（agy/Gemini）、模型驗證
  methodology/    可攜方法論：event-storming、problem-frames、qa-test-design

skills/           Agent 執行介面層（SKILL.md runbook，透過 make install 安裝）
  <skill-name>/   每個 skill 是一個目錄（或指向 plugins/ 的 symlink）
                  scope:global  -- 跨專案可用（方法論、通用工具）
                  scope:project -- 本 repo 限定（需要 tasks/ Python 實作）

tasks/            Python 實作（CLI、service、models、SQLite DB）
commands/         Claude Code slash commands（symlink 到 ~/.claude/commands/）
scripts/          CI 與 lint 工具腳本

Plugin 與 Skill 的差別？

Plugin（plugins/harness、plugins/sdd、plugins/growth、plugins/dev-cycle、plugins/3rd-tools、plugins/methodology） 是有 package.json manifest 的正式 Claude Code plugin，會安裝 hook、rules 和隨附 skill，不需 clone 即可用 claude plugin install 安裝。

Skill（skills/*/SKILL.md）是 runbook 檔案，不是 plugin。透過 make install 以 symlink 安裝到 ~/.claude/skills/，告訴 Claude 如何執行特定工作流程。Skills 無法透過 claude plugin install 個別安裝。

安裝

兩條使用者安裝軌彼此互補：Track 1 安裝 Claude Code 層，Track 2 安裝 tasks-backed skill 所需的 Python CLI。

Track 1 — Claude Code plugin

這條安裝軌提供各 plugin 隨附的 skill、command、rule 與 hook，輕量且不需 clone repo。

claude plugin marketplace add heyu-ai/yibi-stack
claude plugin install harness@yibi-stack
claude plugin install sdd@yibi-stack
claude plugin install growth@yibi-stack
claude plugin install dev-cycle@yibi-stack
claude plugin install methodology@yibi-stack

Track 2 — tasks-backed CLI 工具

這條安裝軌提供 tasks-backed skill 使用的 mycelium、pr-orchestrator 與 portman console script：

uv tool install "yibi-stack @ git+https://github.com/heyu-ai/yibi-stack@v1.23.2"

以下六個 skill 需要 Track 2，依所屬 plugin pack 分組如下：

• growth：pr-control-log、pr-retrospective、mycelium、learn
• dev-cycle：pr-cycle-fast、local-port-manager

若未安裝 Track 2，這些 skill 會在執行任何工作前明確輸出 [FAIL]，並顯示與上方完全相同的安裝提示。

開發者／貢獻者路徑 — local checkout

開發或貢獻 yibi-stack，或需要安裝 repo 管理的 skill、hook 與 scheduler 時，請使用 local checkout。 這條路徑獨立於上方兩條使用者安裝軌。 Tasks-backed harness skills 的 Python 實作仍需要下方 checkout 設定。

# 1. 安裝 plugin（pre-execution hook + 規則）
claude plugin marketplace add heyu-ai/yibi-stack
claude plugin install harness@yibi-stack sdd@yibi-stack growth@yibi-stack dev-cycle@yibi-stack methodology@yibi-stack

# 2. Clone 並安裝 skill + hook + scheduler
git clone https://github.com/heyu-ai/yibi-stack
cd yibi-stack
make install-all

確認安裝狀態（只顯示本 repo 的 skill，排除 gstack / 外部安裝）：

make status-own

主要 Skills

Skill	功能
spectra-amplifier	五層規格展開（透過 sdd plugin）
pr-review-cycle	完整 PR 生命週期：建立 → 並行 review（4 subagent）→ 修正 → CI → merge
pr-cycle-fast	快速 lifecycle orchestrator：Python state machine，可中斷 resume
pr-cycle-deep	深度 lifecycle：mob review（Claude + Codex + Gemini）+ SDD amplifier-verifier
bash-anti-patterns	AP1/AP2/AP3 偵測指南 + shell 引號衛生參考
qa-test-design	六大測試設計技術（等價類別、邊界值、決策表……）
mycelium	跨對話工作交班與洞察收集
bump-version	版本 bump（Flutter/Python/Node/Go）+ CHANGELOG + git tag
protect-push	防止 worktree branch 意外推上 main 的 hook
ci-triage	CI 失敗快速診斷漏斗（Lint → Type → Security → Tests）
learn	瀏覽、搜尋、修剪、匯出教訓記錄
pr-retrospective	PR 收尾五問回顧，路由 lesson 到 .claude/rules/ 或 CLAUDE.md
claude-md-prune	CLAUDE.md 精簡：把 gotcha 路由到 .claude/rules/ 子檔，維持 200 行軟上限
agy	Antigravity CLI（Gemini）第二意見：輕量單一模型 review / 對抗模式
harness-eval	11 維度 harness 就緒度評量，附 PASS/WARN/FAIL 清單與優先改善 TODO

完整索引見 skills/README.md。

Plugins

Plugin	安裝指令	說明
harness	claude plugin install harness@yibi-stack	Harness 就緒度評量（11 維度）+ 執行前 bash 反模式偵測與自動修法指引 + worktree push 保護。
sdd	claude plugin install sdd@yibi-stack	Spectra + OpenSpec 規格展開
growth	claude plugin install growth@yibi-stack	知識萃取與留存：mycelium、learn、PR 回顧／審計、CLAUDE.md 精簡
dev-cycle	claude plugin install dev-cycle@yibi-stack	開發流程：PR cycles、CI 診斷、工作區設定／交班、本機 port 管理、debug
3rd-tools	claude plugin install 3rd-tools@yibi-stack	Codex、Antigravity CLI（agy/Gemini）、模型驗證
methodology	claude plugin install methodology@yibi-stack	可攜方法論：event storming、problem frames、QA test design。

---

License

MIT