cs-onboard

cs-onboard

Bring the repositoryinto the CodeStable workflow system— whether it is a blank slate or already has scattered documents. This skill does only two things:Scaffold、Archive existing docs. Once the scaffold is set up, sub-workflows (feature / issue / compound, etc.) can run directly.

Two paths

Path	Applicable when	Output
Empty repository	The repository has no spec-type documents and no `.codestable/`	Complete scaffold + required scaffold files
Migration	The repository has scattered documents / `docs/` / partial `.codestable/` structure	Audit report + migration mapping plan (confirmed item by item by the user) + written to disk

After startupfirst run one scan to determine automatically, do not make the user choose—they most likely do not know which documents currently exist in the project. If the scan result is ambiguous (e.g., only a README), state the basis for the judgment explicitly and ask the user.

Standard scaffold (target state)

The authoritative version of shared paths and naming conventions is the project's .codestable/reference/shared-conventions.md—this skill copies it over from the skill package. Below only the scaffold files created / checked by onboard are listed.

.codestable/
├── .gitignore                  忽略 CodeStable 运行期 Python 缓存等机器产物
├── attention.md                CodeStable 技能启动必读的项目注意事项
├── requirements/               需求聚合根（空目录 .gitkeep）
│                               （CONTEXT.md / adrs/ 由 cs-domain 按需 lazy 创建）
├── roadmap/                    规划层聚合根
├── goals/                      目标聚合根（bounded goal 自主迭代 + 功能验收）
├── features/                   feature 聚合根
├── issues/                     issue 聚合根
├── refactors/                  重构聚合根（beta）
├── audits/                     审计聚合根
├── brainstorms/                脑暴 / interview 持久记录聚合根
├── compound/                   沉淀类统一目录（cs-keep 写自由 markdown，grep 检索）
├── gates/                      workflow gate 配置（onboard 释放）
│   └── roadmap-goal-gates.yaml roadmap goal 阶段 gate policy
├── tools/                      跨工作流共享脚本（onboard 整目录释放）
│   ├── search-yaml.py / validate-yaml.py
│   ├── codestable-worktree-gate.py / codestable-ai-branch-guard.py / codestable-main-publish.py
│   └── codestable-doctor.py / codestable-spec-governance.py / codestable-dod-runner.py …
├── hooks/                      agent hook 配置（onboard 释放）
│   └── hooks.codex.json        PreToolUse branch-guard，拦截 main/master 上的实现
└── reference/                  跨子技能共享参考（onboard 整目录释放）
    ├── shared-conventions.md / tools.md / maintainer-notes.md
    ├── approval-conventions.md / goal-conventions.md / execution-conventions.md
    └── spec-governance-tools.md / branch-guard-hooks.md / tools-context.md

gates/、tools/ and reference/ are copied wholesale as directories by onboard, automatically bringing along the workflow gate configuration, gate tooling, and shared conventions.hooks/ is an optional branch protection layer; see "Branch protection hook" below for details.

Startup check

First check the current state once：

Check .codestable/: does not exist → empty repository candidate; exists but incomplete → migration (partial completion)
Legacy CodeStable compatibility CodeStable has been renamed multiple times, from easysdd to codestable and then to .codestable. If a legacy codestable directory is encountered, prompt the user:

Legacy codestable detected. It is recommended to directly git mv easysdd .codestable, the structure / frontmatter are fully compatible, and it is ready to use after rename. Shall I execute it?

Agree → git mv easysdd .codestable, follow the migration path (at this point only the possibly missing attention.md、gates/、tools/ and reference/need to be filled in). Want to keep the legacy directory → tell them that sub-skills only read .codestable/, the legacy directory will not be read; follow the empty repository path for a new scaffold
Glob the entire repository .md(excluding node_modules/ .git/): root directory DESIGN.md / ARCHITECTURE.md / SPEC.md / README.md；docs/ doc/ design/ spec/ wiki/; existing .codestable/ files under
Check .codestable/attention.md: if missing, list it as a scaffold item to be filled in
Report the scan conclusion: relevant documents found (list paths) + which path to take + basis for the judgment + uncertain items

Empty repository path

Step 1: Confirm scope with the user

Project name / brief description (referenced when reporting)
attention.md only creates a minimal scaffold; only hard project constraints already given by the user are written in, nothing is filled in out of thin air

Step 2: Create the directory scaffold

Execute in the following order,without waiting for the user to confirm step by step—the scaffold is a one-time whole:

.codestable/{requirements,roadmap,goals,features,issues,refactors,audits,brainstorms,compound}/.gitkeep
.codestable/.gitignore(from the skill package cs-onboard/codestable.gitignore copy, ignoring runtime cache)
.codestable/attention.md(Minimal skeleton template is in the same directory reference.md）
.codestable/gates/(Use cp -rf / Copy-Item -Recurse -Force to copy the entire skill bundle directory cs-onboard/gates/）
.codestable/tools/(Use cp -rf / Copy-Item -Recurse -Force to copy the entire skill bundle directory cs-onboard/tools/，Do not Read then Write）
.codestable/reference/(Same as above)
.codestable/hooks/(Same as above; optional branch protection layer, see "Branch protection hook" below)

requirements/CONTEXT.md and requirements/adrs/ are not in the skeleton—leave them to cs-domain to lazily create the first time the user needs terminology / ADR.

Write to disk with a shell full-directory overwrite, do not Read then Write—these two directories are machine-shared assets; Read+Write will truncate large files, change indentation, eat blank lines, and is slow and wastes tokens. For the specific commands, see migration path step 4.

Step 3: attention.md reminder

attention.md has been created but by default only has an empty skeleton. When reporting, remind the user: if there is information such as compilation prerequisites, test commands, forbidden directories, credential rules, report language preferences, etc. that "must be known every time the CodeStable skill starts," then subsequently use cs-note to append them one by one.

Step 4: Acceptance report

List which files were created:

The CodeStable skeleton is ready. You can now: start a new feature cs-feat / report an issue cs-issue / accumulate knowledge cs-keep

Migration path

Step 1: Generate an audit report

Existing file	Inferred content type	Suggested CodeStable destination	Confidence
`docs/glossary.md`	Domain terminology	`.codestable/requirements/CONTEXT.md`(written by cs-domain)	High
`docs/adr-*.md`	Architecture decisions	`.codestable/requirements/adrs/NNN-{slug}.md`	High
`docs/feature-auth.md`	Feature design draft	`.codestable/features/YYYY-MM-DD-auth/auth-design.md`	Medium
`SPEC.md`	Feature requirements?	Requires user confirmation	Low

Confidence: High = clear semantic match; Medium = inferable but ambiguous; Low = unclear or reasonable to map to multiple locations.

Step 2: Align item by item

For medium / low confidence, use AskUserQuestion to ask:

Medium: give the reasoning for the inference and ask "place it this way?"
Low: describe the file contents, give 2-3 candidate locations + "skip"

Do not ask item by item for high confidence, but list them in the report to give the user a chance to review—asking one by one will make the pace spiral out of control.

Step 3: Handle a partially existing .codestable/

Naming does not conform to the standard (YYYY-MM-DD-{slug} format) but has content → prompt the user and ask whether to rename
Empty placeholder (.gitkeep / empty .md) → fill it in directly without asking

Step 4: Fill in the missing skeleton

Fill in against the standard skeletondirectories / files still missing after user confirmation. Do not overwrite existing content.

.codestable/gates/、.codestable/tools/ and .codestable/reference/ are always overwritten with the new version from the skill bundle—these directories are shared assets maintained by the skill bundle; the authoritative source is in cs-onboard/gates/、cs-onboard/tools/ and cs-onboard/reference/, and the ones in the project are only on-disk copies. One purpose of running onboard again after a skill bundle upgrade is to refresh the copies; keeping old versions will make sub-skills work according to outdated specifications.

Before overwriting, list the files being overwritten in the report so the user knows; only if the user explicitly says "I modified tools/xxx.py, please keep it" should it be exceptionally kept and marked in red. This is the migration pathonly mandatory overwriteactions, other existing files follow "do not touch without confirmation".

Write-to-disk command：

# macOS / Linux
cp -rf <技能包路径>/cs-onboard/gates/.      .codestable/gates/
cp -rf <技能包路径>/cs-onboard/tools/.      .codestable/tools/
cp -rf <技能包路径>/cs-onboard/reference/.  .codestable/reference/
cp -rf <技能包路径>/cs-onboard/hooks/.      .codestable/hooks/
cp -f  <技能包路径>/cs-onboard/codestable.gitignore .codestable/.gitignore
find .codestable/tools -type d -name __pycache__ -prune -exec rm -rf {} +
find .codestable/tools -type f -name '*.pyc' -delete

# Windows PowerShell
Copy-Item -Recurse -Force <技能包路径>\cs-onboard\gates\*      .codestable\gates\
Copy-Item -Recurse -Force <技能包路径>\cs-onboard\tools\*      .codestable\tools\
Copy-Item -Recurse -Force <技能包路径>\cs-onboard\reference\*  .codestable\reference\
Copy-Item -Recurse -Force <技能包路径>\cs-onboard\hooks\*      .codestable\hooks\
Copy-Item -Force <技能包路径>\cs-onboard\codestable.gitignore .codestable\.gitignore
Remove-Item -Recurse -Force .codestable\tools\__pycache__ -ErrorAction SilentlyContinue
Get-ChildItem .codestable\tools -Recurse -Filter *.pyc | Remove-Item -Force

Do not: Read+Write manual copying (truncation / indentation changes), copying one by one with cp (multiple steps, multiple errors), comparing diff first (the rule is unconditional overwrite).

The skill package path is generally the skill installation directory (~/.claude/skills/cs-onboard/ or the plugin directory). If unsure, first ls to locate it. After copying, ls .codestable/gates/ .codestable/tools/ .codestable/reference/ to verify.

Step 5: Handle files not to be migrated

Files the user chose to "skip":do not move / do not delete / do not rename, and in the report mark them as "kept in place (not included in CodeStable)".It is absolutely not allowed to touch them without confirmation—onboard only allows the AI to organize, not to make deletion decisions on the user's behalf.

Step 6: attention.md reminder(same as Step 3 for the empty repository path)

Step 7: Acceptance report

List: migrated files list (from → to), newly created skeleton, unmigrated files (kept in place), next-step suggestions.

Skeleton file template

attention.md For the minimal template see the same directory reference.md。

Branch protection hook (optional)

.codestable/hooks/hooks.codex.json Register a PreToolUse hook, calling .codestable/tools/codestable-ai-branch-guard.py, to intercept when the AI attempts to Edit/Write/Bash code changes on protected branches such as main/master , forcing changes to land on the linked worktree's type branch (feat/ / fix/ / refactor/). For detailed rules see .codestable/reference/branch-guard-hooks.md。

Integration: merge the contents of hooks.codex.json into the agent's hook configuration (Claude Code .claude/settings.json or the Codex equivalent location). onboard only releases the files,it does not automatically modify the agent's global configuration—whether to enable it is decided by the owner.
Invasiveness: once enabled, direct edits on main in daily work will be blocked and must go through the worktree flow. If you do not want this set of strong constraints, do not integrate it; just keep the gate script in tools/ for manual invocation.
Disabling: just remove that entry from the agent hook configuration; the tool script can still be explicitly invoked by each implementation skill.

Line-level code review tool open-code-review (optional)

cs-code-review review has two parts: independent isolated agent review (required) + OCR line-level scan (enhanced). OCR uses the open-code-review 's ocr CLI—after it is installed, cs-code-review will automatically detect and invoke it; if not installed, it naturally degrades without blocking.

1. Installation: detect first; if already installed, do not reinstall

which ocr   # 已经有路径 → 跳过安装，直接进第 2 步

Only when which ocr cannot be found, thenask the owner whether to install(installing is recommended by default); after agreement, install globally:

npm install -g @alibaba-group/open-code-review

Global installation is a change to the owner's environment (requires network access), so confirmation must be obtained before installing; do not execute automatically. If the owner refuses → do not install,cs-code-review if it cannot be detected it will record not-available and continue.

2. Configure LLM: use the provider system, not the old `llm.*` block

⚠️ The easiest pitfall to hit: ocr v1.x uses the provider / providers system. The ocr config set llm.url ...（llm.* block) taught online / in old docs) in the new versiondoes not take effect—even if configured it will be ignored,ocr will still connect to the official endpoint using the default provider, manifesting as ocr llm test getting stuck and timing out (context deadline exceeded）。

ocr isIndependent CLI process, does not reuse the codex / claude agent's model—the agent merely executes the ocr review command on its behalf,ocr and connects to the configured LLM backend itself, which must be configured separately.

Use ocr llm providers to check the built-in provider list. Configuration (using an anthropic-compatible gateway as an example):

ocr config set provider anthropic
ocr config set providers.anthropic.url <网关 base-url>   # 不含 /v1/messages，ocr 按协议自动拼
ocr config set providers.anthropic.api_key <api-key>
ocr config set model <model>                             # 如 claude-opus-4-8
ocr llm test                                             # 必须看到 ✓ Connection test successful

The field name is url , not base_url; under the anthropic protocol ocr will automatically append /v1/messages。
The same applies to an OpenAI-compatible gateway:ocr config set provider <name>(use a built-in provider with the openai protocol or a custom one) + providers.<name>.url + .api_key。
Never fabricate / hardcode an API key on behalf of the owner—only provide a command template for the owner to fill in themselves.

3. Final self-check

Run python3 .codestable/tools/codestable-doctor.py --root ., and the OCR tool: line at the end of the output will report configured / unconfigured / misconfigured / not-installed, and provide precise remediation guidance for mismatches (such as leftover old llm.* blocks, missing providers). doctor only performs static health checks and does not send network requests; connectivity is still determined by ocr llm test .

Exit conditions

.codestable/ Each aggregation root directory (requirements/roadmap/goals/features/issues/refactors/audits/brainstorms/compound) exists
.codestable/.gitignore is installed
.codestable/attention.md has been created
.codestable/gates/、.codestable/tools/、.codestable/reference/、.codestable/hooks/ has been copied from the skill package
The owner has been informed that the branch protection hook is optional and how to enable / disable it
Already which ocr detection: if installed, skip installation and confirm the configuration uses the provider system (not the old llm.* block); if not installed, ask the owner whether to install and record the result
Migration path: every mapping has a clear disposition (migrate / leave in place)
Migration path: no files were moved without confirmation
Acceptance report has been provided

Common pitfalls

Moving / deleting existing files without confirmation—the core principle of migration is that the user makes the call
Filling in substantive content in attention.md on behalf of the user—the project owner must decide this; AI only provides a template
Reintroducing AGENTS.md / CLAUDE.md compatibility paths—CodeStable's startup notes entry point is fixed as .codestable/attention.md
Starting feature/issue work immediately after building the skeleton—onboard is "setting up the environment", not "starting the work"
Executing directly on low confidence—low = must ask
.codestable/gates/、.codestable/tools/ and .codestable/reference/ follow a "do not overwrite" conservative policy—these directoriesmustbe overwritten with the new version from the skill package, otherwise after an upgrade users will be stuck on outdated conventions
Manually moving things with Read + Write—must cp -rf / Copy-Item -Recurse -Force overwrite the entire directory
Bringing __pycache__ / *.pyc into the target project—after copying you must clean up generated caches; local runtime artifacts must not be treated as skill assets
Forgetting to exclude node_modules/ .git/during Glob—this makes scan results full of noise

About this skill

Two paths

Standard scaffold (target state)

Startup check

Empty repository path

Migration path

Skeleton file template

Branch protection hook (optional)

Line-level code review tool open-code-review (optional)

1. Installation: detect first; if already installed, do not reinstall

2. Configure LLM: use the provider system, not the old `llm.*` block

3. Final self-check

Exit conditions

Common pitfalls

Related documentation

cs-onboard

About this skill

Two paths

Standard scaffold (target state)

Startup check

Empty repository path

Migration path

Skeleton file template

Branch protection hook (optional)

Line-level code review tool open-code-review (optional)

1. Installation: detect first; if already installed, do not reinstall

2. Configure LLM: use the provider system, not the old llm.* block

3. Final self-check

Exit conditions

Common pitfalls

Related documentation

2. Configure LLM: use the provider system, not the old `llm.*` block