# Vb Init

> Initialize or reconcile a project for the AI-native VibeRig workflow. Use when the user asks to set up VibeRig, create the V2 project profile and executable Harness manifests, connect an optional tracker, configure gates, or set up the agent team. Do not use to create requirements, tasks, or implementation branches.

- Skill: `jsonlee12138/vb-init` (Agent Skill, multi-file: 7 files)
- Install (CLI): `npx skillmds@latest add jsonlee12138/vb-init`
- Raw SKILL.md: https://api.skillmd.com/api/skills/jsonlee12138/vb-init/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: jsonlee12138 (https://skillmd.com/u/jsonlee12138)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/jsonlee12138/vb-init

---


# VB Init

Prepare a project for the VibeRig Harness: a discover-first V2 project profile, context routes, environment and Runbook manifests, local requirement state, optional tracker registration, agent team, and the global user-approved tool-skill store at `~/.vb-skills`. The knowledge store `~/.vb-wiki` remains lazy and is bootstrapped by `vb-wiki` on its first novelty-gated accepted write.

All steps are **idempotent** — re-running skips what already exists.

## Contract

Single responsibility: initialise or reconcile **one project** and its optional global tool-skill store. Stop and ask when the Linear team/project choice cannot be inferred safely.

Do not create requirements, tasks, branches, dashboards, or MCP runner config.

CLI initialization confirmation and Linear team/project selection are configuration choices. They are not `requirement_confirmation` or `delivery_authorization`, and must not route the user into requirement intake.

## Output

```text
<project-root>/
├── AGENTS.md                    (VibeRig inject block from assets/agents-md-inject.md)
├── CLAUDE.md  ->  AGENTS.md
├── .vibeRig/project.yaml        (see references/project-config-template.md)
├── .vibeRig/context-routes.yaml (path/risk → context, checks and reviewers)
├── .vibeRig/environments.yaml   (environment and credential policy)
├── .vibeRig/runbooks.yaml       (operational trigger and exercise index)
├── .vibeRig/team-profile.yaml   (7 core + evidence-activated conditional agents)
├── .vibeRig/model-routing.yaml  (capability × mode × risk runtime model routes)
├── .vibeRig/prd/                (PRD 目录，含 archive/)
├── .vibeRig/requirements/       (需求目录，含 archive/)
├── .gitignore                   (".worktrees/" entry ensured)
├── .agents/skills/              (pre-installed: insights, skill-builder, skillos-lite)
├── .claude/skills  ->  ../.agents/skills
├── .codex/agents/*.toml         (selected team; Codex models fixed by role)
├── .claude/agents/*.md
├── .cursor/agents/*.md
└── .worktrees/                  (fixed path — not configurable)

~/.vb-skills/                    (user-approved tool-skill git repo, one per machine)
├── .git/
└── vb-skill-lock.json

~/.agents/skills/vb  ->  ~/.vb-skills   (Codex discovery symlink)
~/.claude/skills/vb  ->  ~/.vb-skills   (Claude Code discovery symlink)
```

## Workflow

### 1. Locate project root
Use current workspace or git root unless the user provides a path.
Inspect existing `AGENTS.md`, `.vibeRig/project.yaml`, and `.vibeRig/requirements/`.

### 2. Project scaffolding and explicit V1 migration

Prefer the deterministic CLI:

```bash
viberig init --yes
viberig init --upgrade --yes # only when an existing V1 profile should be reconciled
```

The command never overwrites context/environment/Runbook manifests. `--upgrade` preserves extension keys, migrates `docs.root`, and removes the obsolete `workspace` section. Without the CLI, create equivalent files from the bundled schemas and template.

```bash
mkdir -p .vibeRig/requirements/archive .vibeRig/prd/archive .worktrees
mkdir -p .agents/skills
[ ! -L .claude/skills ] && { mkdir -p .claude; ln -s ../.agents/skills .claude/skills; }

# .worktrees is a fixed path, always ignored — not a config option
grep -qxF '.worktrees/' .gitignore 2>/dev/null || printf '%s\n' '.worktrees/' >> .gitignore
```

Pre-install `insights`, `skill-builder`, `skillos-lite` at project level via `find-skills`.
Log missing skills in the init report; do not abort.

### 3. Global approved tool-skill store (idempotent)

This store is not the default learning destination. It is prepared so an explicitly authorized `vb-learn` invocation can install a tool skill later; ordinary accepted-work learning goes to the lazy `~/.vb-wiki` store.

```bash
# a. Init git repo
git -C ~/.vb-skills rev-parse --git-dir 2>/dev/null \
  || git init ~/.vb-skills

# b. Create empty lock if absent
if [ ! -f ~/.vb-skills/vb-skill-lock.json ]; then
  printf '{\n  "version": 1,\n  "skills": {}\n}\n' \
    > ~/.vb-skills/vb-skill-lock.json
  git -C ~/.vb-skills add vb-skill-lock.json
  git -C ~/.vb-skills commit -m "chore: init vb-skill-lock"
fi

# c. Codex discovery symlink — MUST be inside ~/.agents/skills/
mkdir -p ~/.agents/skills
[ ! -L ~/.agents/skills/vb ] \
  && ln -s ~/.vb-skills ~/.agents/skills/vb

# d. Claude Code discovery symlink
mkdir -p ~/.claude/skills
[ ! -L ~/.claude/skills/vb ] \
  && ln -s ~/.vb-skills ~/.claude/skills/vb
```

> **Critical**: symlinks must be `~/.agents/skills/vb → ~/.vb-skills` and `~/.claude/skills/vb → ~/.vb-skills`.
> `~/.agents/vb` (sibling of `skills/`) is outside Codex scan depth and will never be discovered.

### 4. Project Profile and Harness manifests

Create or update `.vibeRig/project.yaml` from [references/project-config-template.md](./references/project-config-template.md).
Validate against [project-profile.schema.json](./assets/project-profile.schema.json). Required fields include document discovery and context routing, environment profile, executable project commands, Evidence retention, tracking adapter, output language, PR/Gate policy and the four recurring Subagent defaults.
There is no `workspace` section — the worktree root is always the fixed project path `.worktrees/`.

Validate `.vibeRig/context-routes.yaml`, `.vibeRig/environments.yaml` and `.vibeRig/runbooks.yaml` against their bundled schemas. Discover existing project commands and documentation before filling optional values; do not invent commands or force a standard `docs/` tree.

### 5. AGENTS.md

Copy the inject block from [assets/agents-md-inject.md](./assets/agents-md-inject.md) between
`<!-- inject:viberig:start -->` and `<!-- inject:viberig:end -->` tags.
Preserve all unrelated project rules already in `AGENTS.md`.

```bash
[ ! -L CLAUDE.md ] && [ ! -e CLAUDE.md ] && ln -s AGENTS.md CLAUDE.md
```

Claude Code reads `CLAUDE.md` by convention; symlink it to `AGENTS.md` so both platforms share one source of truth. Skip if `CLAUDE.md` already exists as a real file (do not overwrite user content).

### 6. Linear registration

See the `vb-linear` skill for tool selection and fallback behavior.

**6a. 登录校验（先于任何 project 操作）**

请 `vb-linear` 探测登录态（用任意只读能力，如解析 team）：
- 返回正常 → 已登录，进入 6b。
- 报鉴权/未授权错误，或 Linear MCP 未连接 → 未登录，触发 Linear OAuth 登录流程，等待用户完成授权后重试探测一次。仍失败则按 Linear 工具不可用处理（见下）。

**6b. Project 注册**（仅在 6a 确认已登录后执行）
- 请 `vb-linear` 解析 team。
- 请 `vb-linear` 查找已有 project（先查重再建）。
- 仅当未查到时，请 `vb-linear` 创建 project。该 Project 是**常驻容器**：后续所有需求的 Milestone / Issue 都挂在它下面（里程碑原生工作流），不要按需求另建 Project。
- 请 `vb-linear` 查找/创建 Project Document。
- Write resolved Linear ids to `project.yaml`.

Report as **partial** when Linear tools are unavailable (including login declined/failed); do not claim full registration.

### 7. Agent team and runtime model routing

Read [team composition policy](../update-team/references/team-composition.md) before materializing Agents.

**7a. 安装七个 core Agents**

调用 `built-in-agents --core`，仅将 `researcher`、`implementation`、`test_engineer`、`code_review`、`qa`、`security_auditor`、`integrator` 渲染到 Codex、Claude Code、Cursor。不得把 manifest 的完整 `agents[]` 当作 init 默认集合。未修改的旧文件可升级；用户定制文件不覆盖；废弃 Agent 只报告，不自动删除。

**7b. 调用 `update-team` 激活 conditional Agents**

调用 `update-team`，基于 `.vibeRig/requirements/`、`.vibeRig/prd/`、Linear 未执行 work items 和实际项目结构：

1. 为 backend、frontend、data、UI/UX、reliability 和 architecture red-team 收集正向证据；
2. 只把证据命中的 conditional Agent 精确列表交给 `built-in-agents --only`；存在 backend E2E TC/contract 时必须包含 `backend_e2e_engineer`；
3. 将 truly project-specific 角色交给 `agent-creator`；
4. 生成并 schema 校验 `.vibeRig/team-profile.yaml`；
5. 保留未选中但已存在或定制的 Agent，不自动删除。

**7c. 生成 Codex runtime model routes**

由 `update-team` 生成 `.vibeRig/model-routing.yaml`。Portable spec 保持 `model: inherit`，但 Codex 原生 Agent 文件必须应用 manifest 固定默认模型，避免父会话漏掉分发：

- `researcher`、`implementation`、`test_engineer` → Luna；
- `code_review`、`qa`、`integrator` 和领域架构 Agent → Terra；
- `backend_e2e_engineer`、`security_auditor`、`architecture_red_team` → Sol；
- Claude Code/Cursor 缺少自身 accepted Evidence 时保持 `inherit`。

`test_engineer` 只负责 unit/contract/integration/regression；backend E2E 必须委派给独立 `backend_e2e_engineer`。`.vibeRig/model-routing.yaml` 继续记录 capability、mode/task family、risk、fallback 和 escalation，不得把 challenger 写入 Agent 文件。

### 8. Report

Project Profile version, AGENTS.md, context routes, environment/credential boundary, Runbook policy, docs owner mode, output language, tracker status,
gate policy, core/conditional team evidence (created / existed / dormant / skipped), runtime model routes, approved tool-skill store status, and the fact that `vb-wiki` bootstraps its knowledge store lazily.

## Validation

```bash
# Local project
ls .vibeRig/project.yaml .vibeRig/context-routes.yaml .vibeRig/environments.yaml .vibeRig/runbooks.yaml .vibeRig/requirements/ .worktrees/ AGENTS.md
grep 'version: 2' .vibeRig/project.yaml
grep "language:" .vibeRig/project.yaml
grep -qxF '.worktrees/' .gitignore && echo "gitignore ok"
test -L CLAUDE.md && readlink CLAUDE.md | grep -q AGENTS.md && echo "symlink ok"
test -L .claude/skills && echo "symlink ok"
ls .agents/skills/insights/ .agents/skills/skill-builder/ .agents/skills/skillos-lite/
ls .codex/agents/*.toml .claude/agents/*.md .cursor/agents/*.md
grep -E "coreAgents|conditionalAgents|manifestFingerprint|policyFingerprint" .vibeRig/team-profile.yaml
grep -E "capability|taskFamily|qualityFloor" .vibeRig/model-routing.yaml
node <viberig-root>/scripts/validate-rendered-agent-models.mjs \
  --root . --agents <selected-agent-csv> --platforms codex,claude,cursor

# Global approved tool-skill store
git -C ~/.vb-skills rev-parse --git-dir && echo "vb-skills git ok"
ls ~/.vb-skills/vb-skill-lock.json
test -L ~/.agents/skills/vb \
  && readlink ~/.agents/skills/vb | grep -q vb-skills \
  && echo "symlink ok" || echo "SYMLINK MISSING"
test -L ~/.claude/skills/vb \
  && readlink ~/.claude/skills/vb | grep -q vb-skills \
  && echo "symlink ok" || echo "SYMLINK MISSING"
```

- [ ] `.vibeRig/project.yaml` is V2, has document/environment/evidence/tracking contracts and no legacy `docs` or `workspace` section.
- [ ] Context routes, environment profiles and Runbook index exist, preserve project truth owners and pass their schemas.
- [ ] Root `AGENTS.md` contains the VibeRig inject block.
- [ ] `CLAUDE.md` symlinks to `AGENTS.md` (or was already a real file, left untouched).
- [ ] `.claude/skills` symlinks to `../.agents/skills`.
- [ ] `insights`, `skill-builder`, `skillos-lite` present in `.agents/skills/`.
- [ ] 七个 core Agents 跨目标平台存在（或 gap 明确报告）。
- [ ] 每个 conditional Agent 都有 `.vibeRig/team-profile.yaml` 中的正向 evidence；无证据的领域角色未在全新项目中物化。
- [ ] Codex Agent 文件固定模型符合 manifest；Claude Code/Cursor 未继承 Codex slug。
- [ ] Luna 处理 research/implementation/普通测试；Terra 处理 Review/QA/Integration/领域设计；Sol 处理独立 backend E2E/Security/Red Team。
- [ ] `test_engineer` 与 `backend_e2e_engineer` 分离；受保护 Gate 不探索。
- [ ] `.worktrees/` exists and is listed in `.gitignore`.
- [ ] `~/.vb-skills` is a git repo with `vb-skill-lock.json`.
- [ ] `~/.agents/skills/vb` and `~/.claude/skills/vb` both symlink to `~/.vb-skills`.
- [ ] Linear login was verified (or login was triggered) before any project-creation call to `vb-linear`.
- [ ] Linear registration complete, or partial explicitly reported.

## Hard Rules

- Do not add VibeRig MCP settings to `.codex/config.toml`.
- Do not start or register a local VibeRig dashboard.
- Do not place the Codex symlink at `~/.agents/vb` — it must be `~/.agents/skills/vb`.
- Do not report full initialization when Linear tools were available but registration was skipped.
- Do not install all entries in `agents.manifest.json` by default; init materializes core plus evidence-selected conditional Agents.
- Do not leave Codex Agent models to `inherit`; apply `platformModelDefaults.codex` exactly. Do not copy those slugs to Claude Code/Cursor.
- Do not make CI mandatory for all projects — record the project's own gate policy.
- Do not add a `workspace` section or a `worktrees_root` setting to `project.yaml` — the worktree path is always the fixed `.worktrees/`.
- Do not overwrite an existing real `CLAUDE.md` file with a symlink.
- Do not ask `vb-linear` to create a project (or make any Linear write) before verifying login in step 6a; if not logged in, trigger the OAuth flow first.