vibe-instruction

name	vibe-instruction
description	Use when you need an overview of the Vibe Center project, its implementations (vibe2 shell and vibe3 python), the available commands, and the standard development workflow. This is the meta-skill that orients any agent to the project.

/vibe-instruction - 项目导览

Overview

这是所有 agent 的入口导览技能。用于快速了解项目结构、可用命令和开发工作流。

When to Use

用于首次进入项目、需要定位命令或工作流入口、或者不知道应调用哪个 Vibe skill 的场景。

Required Reading

• AGENTS.md
• docs/standards/v3/skill-trigger-standard.md

职责边界

• 负责：项目索引、命令分层说明、把用户路由到正确 workflow / skill / 标准文档
• 不负责：安装诊断、项目配置补全、skills 盘点、运行态故障排查

分流规则：

• 机器级安装、CLI / hooks / MCP / keys / doctor 检查 → skills/vibe-onboard/SKILL.md
• 当前 repo 的工具、配置、prompt readiness 检查 → skills/vibe-project-check/SKILL.md
• skills 安装、symlink、全局/项目级对齐 → skills/vibe-skills-manager/SKILL.md

如果用户问题涉及 Claude / Codex 外部工具链、skills、hooks、MCP、claude-mem、安装兼容性或环境对齐，在继续前先读取：

• docs/standards/plugin-setup-standard.md

这份标准是当前项目关于两类 agent 工具链对齐、已知上游问题和本机规避策略的真源。

---

项目结构概览

Vibe Center 包含两个并行实现：

vibe-center/
  bin/vibe          # V2 Shell 入口 (重定向到 V3)
  lib/              # V2 Shell 核心逻辑
  config/shell/aliases.sh # V2 alias 定义
  src/vibe3/        # V3 Python 实现 (当前核心)
  skills/           # AI agent 技能集 (Markdown)
  .agent/           # 规则、规范、工作流、Supervisor 上下文

---

V2 Shell 部分（vibe2）

V2 提供底层 alias 和环境工具。

使用原则：

• vibe / bin/vibe 主要用于 V2 shell 环境、alias、keys、tooling 入口。
• 不要把 vibe 当成 V3 orchestration / flow / task / PR 的主入口。
• 遇到 V3 语义时，优先使用 vibe3 或 uv run python src/vibe3/cli.py ...。

核心 alias：

alias	含义
wtnew <branch>	创建新 worktree（git worktree add）
vup	更新主仓库 + 当前 worktree

V2 环境命令：

bin/vibe check          # 验证环境 (V2 版)
bin/vibe tool           # 工具管理
bin/vibe keys <check|get|init>  # 密钥管理

---

V3 Python 部分（vibe3）

V3 是当前的人机协作编排层，负责 issue / branch / PR 的创联与本地 flow / handoff 协作增强。

运行方式：

# 推荐给 agent / tmux / server 子进程使用仓库真源入口
uv run python src/vibe3/cli.py <command>
# 人类本地交互可以继续使用 alias
vibe3 <command>

命令使用原则：

• agent、tmux、后台子进程、server、脚本里优先使用 uv run python src/vibe3/cli.py ...。
• 人类本地交互可以使用 vibe3 ... alias。
• 文档里首次提到命令时，优先区分 vibe（V2 shell）和 vibe3（V3 orchestration / flow / task / PR）。
• vibe 继续负责 shell 环境、alias、keys、tooling；vibe3 负责 flow / task / orchestra / PR / review。
• 不要把 vibe check 和 vibe3 check 混为一谈；前者是 V2 环境检查，后者是 flow/task 同步审计。

核心命令组

status - 全局看板（主入口）

vibe3 task status             # 查看所有活跃 flow、Orchestra 追踪进度及环境状态

补充语义：

• task status 是当前 runtime scene 的主观察入口。
• orchestra ready queue、active issues、blocked issues 优先通过这里看。
• 需要看”主线现在能不能继续调试”，先看 task status。
• 注意：CLI 有一个隐藏的顶层 status 命令（兼容性保留），实际等同于 task status。

flow - 逻辑现场管理

uv run python src/vibe3/cli.py flow show          # [高频] 查看当前分支绑定的 task、PR、milestone 及 Timeline
uv run python src/vibe3/cli.py flow status        # 仅查看活跃 flow 列表
uv run python src/vibe3/cli.py flow update        # [高频] 注册当前分支为 flow，或更新其 metadata
uv run python src/vibe3/cli.py flow bind <issue>  # [高频] 绑定 issue 到当前 flow (role: task/related/dependency)
uv run python src/vibe3/cli.py flow blocked       # 标记当前 flow 为阻塞，并记录原因

补充语义：

• flow show 看当前分支是不是已注册 flow，以及该 flow 的 PR / task / handoff 现场。
• flow status 看全局 flow 列表，不替代 task status 的 orchestra 看板作用。
• 如果当前分支尚未注册 flow，先 flow update，再继续把它当作正式现场。

check / resume - 审计与恢复

uv run python src/vibe3/cli.py check                  # 检查 flow 和 task 是否同步
uv run python src/vibe3/cli.py task resume 456        # 恢复特定 issue（默认 --label auto）
uv run python src/vibe3/cli.py task resume 456 --label auto  # 显式指定自动推断恢复
uv run python src/vibe3/cli.py task resume --blocked  # 批量恢复所有 blocked issues（谨慎使用）
uv run python src/vibe3/cli.py flow rebuild 456       # 显式重建，删除并重建 flow/worktree

补充语义：

• check 是同步审计，不是默认的”看现场”命令。
• task resume <issue-number> 用于恢复特定 issue，清除 blocked 状态并推断恢复 label，不删除现场。
• task resume --blocked 批量恢复所有 blocked issues（谨慎使用，可能影响多个现场）。
• flow rebuild 用于显式删除并重建 flow scene，是 destructive 操作。
• task resume 不再表示重建；它默认是 --label auto。
• 需要删除 flow/worktree 时使用 flow rebuild，不要用 task resume 隐式触发。

settings - 治理真源

cat config/v3/loc_limits.yaml

补充语义：

• config/v3/loc_limits.yaml 是代码总量、单文件 LOC 限制和 exception 的真源。
• 总量命中阈值时，默认动作不是机械阻断，而是触发一轮代码质量复查。
• 单文件命中默认或 max 限制时，先判断是否值得拆分；若不值得拆分，再进入 exception 流程。
• 任何”允许提升总量”或”允许单文件例外”的判断，都应回写到 config/v3/loc_limits.yaml 并附 reason。

run - Agent 执行引擎

vibe3 run --branch <branch>              # 执行 flow 的 plan（自动读取 plan_ref）
vibe3 run --branch <branch> --no-async   # 同步执行（阻塞）
vibe3 run --branch <branch> --publish    # 提交模式：创建 commit + PR
vibe3 run --skill <name>                 # 派发特定 skill 执行
vibe3 run "指令描述"                      # 派发自定义指令执行（lightweight 模式）

补充语义：

• 默认异步执行（在 tmux session 中），无需指定 --async。
• --branch 可接受分支名或 issue 编号（如 2428 或 dev/issue-2428）。
• 无 --plan 参数时，自动从 flow_state.plan_ref 读取计划。
• --publish 模式会自动创建 commit 和 PR。
• --skill 和 --publish 互斥。

plan - 计划生成

vibe3 plan --branch <branch>        # 基于 issue/branch 现场生成实现计划
vibe3 plan --spec <spec-ref>        # 基于 spec 文件、issue number 或 @spec 生成实现计划

handoff - 协作交接记录

vibe3 handoff status                      # 查看当前分支的 agent 交接链
vibe3 handoff show @plan --branch <b>     # 读取计划 artifact
vibe3 handoff show @report --branch <b>   # 读取执行报告
vibe3 handoff show @audit --branch <b>    # 读取审查报告
vibe3 handoff show @current               # 读取当前分支的 handoff
vibe3 handoff append "..." --kind note    # 记录关键发现或里程碑

补充语义：

• @plan、@report、@audit、@spec 是特殊别名，从 flow_state 的对应 ref 字段解析。
• @current 读取当前分支的 current.md。
• 其他路径（如 @task-xxx/run.md）为共享 artifact，忽略 --branch。

inspect - 代码智能分析

vibe3 inspect symbols <file>:<symbol> # 查看经范围校验的静态引用证据
vibe3 inspect base origin/main        # 查看精确 Git 改动与 Kernel review 等级
vibe3 inspect files <file.py>         # 查看单个 Python 文件的 AST 事实

pr - Pull Request 管理

vibe3 pr create --base main --yes     # 创建 PR
vibe3 pr show                         # 查看 PR 详情和变更分析
vibe3 pr ready                        # 标记 PR 为 ready for review

review - 代码审查

vibe3 review --branch <branch>         # 审查 issue 实现（orchestra-driven）
vibe3 review base origin/main          # 审查本地变更 vs base branch

scan - 治理和监督扫描

vibe3 scan governance    # 运行治理扫描
vibe3 scan supervisor    # 运行监督扫描
vibe3 scan all           # 运行所有扫描

补充语义：

• 不启动服务器的情况下运行一次性扫描。

serve - Orchestra 服务器

vibe3 serve start     # 启动 Orchestra 服务器
vibe3 serve status    # 显示服务器状态、FailedGate 状态和近期活动
vibe3 serve stop      # 停止服务器
vibe3 serve resume    # 清除 FailedGate，允许 orchestra 恢复
vibe3 serve logs      # 显示服务器日志

补充语义：

• Orchestra 是后台服务，通过心跳轮询自动处理 Webhook 事件。
• vibe3 task status 是它的主展示面。

mcp - MCP 服务器

vibe3 mcp run  # 在 stdio 模式下运行 MCP 服务器（用于 MCP 客户端集成）

ask - 项目知识问答

vibe3 ask "问题内容"  # 询问关于项目的问题

---

Execution Flow（开发工作流）

本项目采用双轨模型（权威：spec-kit-workflow-standard.md）：

轨	适用	入口
spec-kit 轨（人机协作首选）	非平凡变更、新 feature、需 spec 设计	/speckit-* skills
vibe3 flow 轨（自动化后端）	issue body 已明确、琐碎修复、文档改动	/vibe-continue

vibe3 plan/run/review 是 issue-driven 自动化后端，通常不作为人机协作首选入口；spec/explore 阶段保持人机协作走 spec-kit 轨。openspec 不是本项目推荐工作流，统一用 spec-kit。

1. 启动任务

/vibe-new <issue-number>        # 创建 flow/branch/worktree，自动扫描 spec 状态并推荐阶段
/vibe-continue                  # 恢复已有 branch，按 spec status 分流到正确轨

2. 检查 spec 状态 + 推荐阶段

/speckit-superspec-status       # 扫描 .specify/specs/，输出每 spec 阶段 + Suggested next step
vibe3 flow show                 # 确认 spec_ref / plan_ref / report_ref / audit_ref

依 suggested next step 选择轨（详见 /vibe-new Step 7.5 / /vibe-continue Step 1.5）。

3. 推进执行

• spec-kit 轨：/speckit-<phase>（brainstorm → specify → plan → tasks → implement → review）
• vibe3 flow 轨：/vibe-continue（plan → run → review → publish）

4. 提交与收口

/vibe-commit                     # 整理变更并推送到 PR
/vibe-integrate                  # 等待 CI 与 Review，直到 merge-ready
/vibe-done                       # PR 进入终态后做 issue / handoff / 现场收口

---

Guardrails（核心边界与误区）

1. flow ≠ branch：flow 是绑定在 branch 上的逻辑上下文；branch 生命周期优先由 git / gh 管理。
2. 真源在 .git/vibe3/handoff.db：所有 worktree 共享该 SQLite 数据库，由主仓库的 git common dir 承载。
3. 不再有 flow new / flow done / 顶层 status：V3 只保留最小共享状态入口；branch / issue / PR 常规生命周期优先直接使用 git / gh。
4. handoff 不是数据库：.git/vibe3/handoff/ 存储的是 Markdown 交接文件，用于人机协作；状态流转以 SQLite 库为准。
   • handoff status 看当前 flow 的交接现场。
   • handoff show <artifact-path> 读取共享 artifact，不再把 handoff show 当成状态总览入口。
5. 恢复已有 branch 统一用 /vibe-continue：/vibe-start 已不再作为现行入口。
6. Orchestra 是后台服务：vibe3 serve 启动心跳轮询，自动处理 Webhook 事件，vibe3 task status 是它的主展示面。
7. 现场判断顺序有主次：先 task status / flow status / flow show 看现场，再用 check 核对同步；blocked 用 task resume 恢复，坏现场用 flow rebuild 重建。

---

故障排查

• 先看现场：运行 vibe3 task status，必要时补 vibe3 flow status / vibe3 flow show。
• 状态不一致：运行 vibe3 check 进行同步审计。
• 恢复特定 blocked issue：运行 vibe3 task resume <issue-number> --label auto。
• 批量恢复 blocked issues：运行 vibe3 task resume --blocked（谨慎使用，会恢复所有 blocked issues）。
• 代码总量 / 单文件超限：先看 config/v3/loc_limits.yaml 的阈值与 exceptions，再决定是否进入质量复查或 exception 处理。
• 环境配置：查看 config/v3/settings.yaml。
• 调用追踪：任何命令加 --trace 可查看内部调用栈。
• 权限/API 错误：运行 bin/vibe keys check 检查 Token 状态。