cs-onboard

Onboard a repository into the CodeStable workflow system—whether it's a blank slate or a repository with scattered documents. This skill only does two things: build the skeleton and organize existing documents. After the skeleton is built, sub-workflows (feature / issue / compound, etc.) can run directly on it without needing to explain where directories are located.

Two Paths

Path	Applicable Scenario	Output
Empty Repository Path	No spec-type documents or `codestable/` directory in the repository	Complete `codestable/` directory skeleton + necessary skeleton files
Migration Path	The repository already has scattered documents, `docs/` directory, architecture documents, design drafts, or partial `codestable/` structure	Audit report + migration mapping plan (confirmed by user one by one) + finalization

After starting, automatically scan first to determine the path—don't let users choose themselves, as they probably don't know what documents are currently in the project. If the scan result is ambiguous (e.g., only a README exists), clearly state the basis for judgment and ask the user for confirmation.

Involved Paths

After onboarding is completed, the authoritative version of shared paths and naming conventions is
codestable/reference/shared-conventions.md
in the project—copied from the skill package by this skill. Only the skeleton files that need to be created or checked during onboarding are listed below.

Standard Skeleton (Target State)

The following skeleton should exist in the repository after onboarding:

codestable/
├── requirements/               ← Root directory for requirement aggregation (empty directory, .gitkeep): "Why this capability is needed" (only records current status)
├── architecture/
│   └── DESIGN.md               ← Architecture entry skeleton (placeholder template when first created): "What structure to use for implementation" (only records current status)
├── roadmap/                    ← Root directory for planning layer aggregation (empty directory, .gitkeep): "Plans for future development", independent of current status archives
├── features/                   ← Root directory for feature aggregation (empty directory, .gitkeep)
├── issues/                     ← Root directory for issue aggregation (empty directory, .gitkeep)
├── compound/                   ← Unified directory for accumulated content (empty directory, .gitkeep): learning / trick / decision / explore four document types are distinguished by doc_type + the type segment in the middle of the filename (YYYY-MM-DD-{doc_type}-{slug}.md)
├── tools/                      ← Cross-workflow shared script tools (released from the skill package during onboarding)
│   ├── search-yaml.py          ← General YAML frontmatter search tool
│   └── validate-yaml.py        ← YAML syntax validation tool
└── reference/                  ← Reference documents shared across sub-skills (released from the skill package during onboarding)
    ├── shared-conventions.md   ← Shared metadata standards, checklist lifecycle, recommended phase closure practices
    ├── tools.md                ← Usage reference for shared scripts
    └── maintainer-notes.md     ← Breakpoint recovery, extension points, maintenance rules

AGENTS.md

is in the project root directory, not in
codestable/
. Onboarding will check if it exists; if not, it will remind the user but not write it on their behalf—the content of AGENTS.md is highly project-specific and must be filled in by humans. The absence of

AGENTS.md

does not block the completion of onboarding, but users need to complete it before starting subsequent feature / issue / acceptance phases, or explicitly accept that the current repository temporarily has no project-level hard constraint entry.

Startup Checks

Perform the following scans when starting, scan first before speaking, don't ask questions blindly:

Check if the
codestable/
directory exists
- Does not exist: Candidate for empty repository path
- Exists but incomplete: Migration path (partial completion)

1.5. Check if the old
easysdd/
directory exists (legacy from 2026 renaming)

The old name of CodeStable was easysdd. After the full renaming in 2026, the project directory was changed from

easysdd/

codestable/

. When an

easysdd/

directory is found in the repository (and no

codestable/

exists), stop and prompt the user to migrate:

Detected the old
easysdd/
directory (predecessor of CodeStable). It is recommended to directly run
git mv easysdd codestable
to rename the directory. The file structure and frontmatter fields in the original directory are completely compatible, and it can be used directly after renaming. Would you like me to execute this for you?

If the user agrees → Execute

git mv easysdd codestable

, then continue processing according to the "migration path" (at this point

codestable/

already exists with complete content, only need to supplement the missing shared assets

tools/

and

reference/

). If the user wants to keep the old directory without migrating → Inform them that CodeStable sub-skills only read the

codestable/

path, and products under the old

easysdd/

will not be read; continue to create a new skeleton according to the empty repository path.

Glob all
.md
files in the repository (excluding
```
node_modules/
```
,
```
.git/
```
), focus on:
- ```
DESIGN.md
```
  ,
```
ARCHITECTURE.md
```
  ,
```
SPEC.md
```
  ,
```
README.md
```
  in the root directory
- Files in directories such as
```
docs/
```
  ,
```
doc/
```
  ,
```
design/
```
  ,
```
spec/
```
  ,
```
wiki/
```
- Existing files in the current
```
codestable/
```
  directory
Check if
AGENTS.md
exists (root directory)
Report scan conclusions—clearly state in one paragraph:
- Which documents related to the CodeStable system were found (list file paths)
- Which path is determined and the basis for judgment
- Which uncertain items require user confirmation

Empty Repository Path

Applicable Conditions

No spec-type documents in the repository (or only
```
README.md
```
)
```
codestable/
```
directory does not exist

Execution Steps

Step 1: Confirm scope with the user

Explain the content to be created (see "Standard Skeleton" above), and ask the user:

Project name / introduction (to be filled into the
```
DESIGN.md
```
placeholder template)
Whether
```
AGENTS.md
```
already exists; if not, whether to fill it now—if yes, guide them to fill in key fields; if later, remind them that it will be read when the feature/issue workflow starts

Step 2: Create directory skeleton

Execute in the following order, proceed after each step is completed, do not wait for user step-by-step confirmation—the skeleton is created as a whole at once, step-by-step confirmation will disrupt the rhythm:

```
codestable/requirements/.gitkeep
```
```
codestable/architecture/DESIGN.md
```
(fill in the placeholder template, see
```
reference.md
```
in the same directory)
```
codestable/roadmap/.gitkeep
```
```
codestable/features/.gitkeep
```
```
codestable/issues/.gitkeep
```
```
codestable/compound/.gitkeep
```
```
codestable/tools/
```
(copy all files under
```
cs-onboard/tools/
```
in this skill package using
```
cp -rf
```
/
```
Copy-Item -Recurse -Force
```
for the entire directory, do not Read then Write)
```
codestable/reference/
```
(same as above, copy the entire directory from
```
cs-onboard/reference/
```
in this skill package—this is the only way all CodeStable sub-skills share reference documents during runtime)

Use shell commands to overwrite the entire directory when finalizing, do not
Read
a file then
Write
it—these two directories are machine-shared assets, and the Read+Write link can easily truncate large files, modify indentation, eat blank lines, and is slow and token-consuming. Specific command examples are given in Step 4 of the migration path, and the empty repository path should follow the same execution.

Step 3: Reminder about AGENTS.md

AGENTS.md

does not exist in the root directory:

AGENTS.md
does not exist yet. It is the "project hard constraint entry" for all CodeStable sub-workflows—recording code specifications, known pitfalls, and prohibited items. It is recommended to create a minimal version now. Would you like to fill it in now, or create it later yourself?

If the user selects "fill in now": Provide a minimal template (see

reference.md

in the same directory), guide the user to fill in key fields and save. If the user selects "later": Record it in the report and inform the user "remember to supplement it before triggering the feature/issue workflow next time".

Step 4: Acceptance Report

List the files created and inform the user:

CodeStable skeleton is ready. Now you can:
Start a new feature: Trigger the
cs-feat
skill
Report an issue: Trigger the
cs-issue
skill
Accumulate knowledge: Trigger the
cs-learn
skill

Migration Path

Applicable Conditions

The repository has scattered spec-type documents, design documents, or partial

codestable/

structure.

Execution Steps

Step 1: Generate Audit Report

Organize the scan results into a mapping table and display it to the user:

Existing File	Inferred Content Type	Suggested CodeStable Location	Confidence
`docs/DESIGN.md`	Project architecture document	`codestable/architecture/DESIGN.md`	High
`docs/feature-auth.md`	Design draft of a feature	`codestable/features/YYYY-MM-DD-auth/auth-design.md`	Medium
`SPEC.md`	Feature requirement document?	Need user confirmation	Low
...	...	...	...

Meaning of Confidence:

High: The file content clearly matches the semantic meaning of the target location (e.g., architecture documents are placed in the architecture directory)
Medium: Inference is possible but ambiguous (e.g., a document mixes requirements, design, and acceptance content)
Low: The file content is unclear, or it can be mapped to multiple positions reasonably

Step 2: Align with the user item by item

For each mapping with "Medium" or "Low" confidence, use

AskUserQuestion

to ask the user for confirmation:

Medium confidence: Provide the reasoning for the inference and ask "Is this the correct way to organize it?"
Low confidence: Describe the file content, provide 2-3 candidate locations for the user to select from, and offer a "Skip (do not migrate)" option

Mappings with high confidence do not need to be asked item by item, but should be listed in the report to give the user a chance to object. The reason is that high-confidence judgments may also be wrong, but item-by-item questioning will disrupt the rhythm—listing them in the report gives the user a review opportunity without interrupting the process.

Step 3: Handle CodeStable Documents "Written Halfway"

codestable/

already exists partially:

Check if existing directories comply with naming conventions (format
```
YYYY-MM-DD-{slug}
```
)
Check if existing files have content (empty files vs. content-filled files)
Files that do not comply with conventions but have content: Prompt the user and ask if they want to rename them
Empty placeholder files (
```
.gitkeep
```
or empty
```
.md
```
): Directly supplement them without asking the user

Step 4: Supplement Missing Skeleton

Compare with the standard skeleton above and supplement the missing directories and files after the user confirms the migration plan. Do not overwrite directories with existing content, only supplement vacancies.

codestable/tools/
and
codestable/reference/
are always overwritten with the latest version from the skill package—regardless of whether the old version in the project seems to have been modified.

These two directories are shared assets maintained by the skill package, with the authoritative source in
```
cs-onboard/tools/
```
and
```
cs-onboard/reference/
```
, and the version in the project is just a local copy
After the skill package is upgraded (e.g., bug fixes, added fields, modified scripts), one of the purposes of running onboarding again is to refresh the old copy to the new version; keeping the old version will cause subsequent sub-skills to work according to outdated standards
Before overwriting, list the files to be overwritten in the report so the user knows what is happening; if the user explicitly said "I modified tools/xxx.py, please keep it", then keep it and mark it in red in the report

This is the only mandatory overwrite action in the migration path. All other existing files (architecture / features / issues / compound / AGENTS.md, etc.) still follow the principle of "do not modify without user confirmation".

Finalization method: Directly use shell commands to overwrite the entire directory, do not Read then Write.

Correct approach (batch overwrite with one command):

bash

# macOS / Linux
cp -rf <skill package path>/cs-onboard/tools/.      codestable/tools/
cp -rf <skill package path>/cs-onboard/reference/.  codestable/reference/

# Windows PowerShell
Copy-Item -Recurse -Force <skill package path>\cs-onboard\tools\*      CodeStable\tools\
Copy-Item -Recurse -Force <skill package path>\cs-onboard\reference\*  CodeStable\reference\

Incorrect approaches (do not do this):

❌ Use a Read tool to read files from the skill package, then use a Write tool to paste them into the project—large files will be truncated, indentation will be changed, blank lines will be eaten, and it is slow, token-consuming, and easy to copy incorrectly
❌
```
cp
```
files one by one—each extra step increases the chance of error
❌ Compare diffs before deciding whether to copy—the rule for these two directories is "unconditional overwrite", comparing diffs is a waste of effort

The skill package path is generally the installation directory of the current skill (e.g.,

~/.claude/skills/cs-onboard/

or the corresponding location in the plugin directory). If unsure, first use

ls

to locate it, then execute the copy. After copying, run

ls codestable/tools/ codestable/reference/

to verify all files are present.

Step 5: Handle Files Not Migrated

Files the user chooses to "Skip": Do not move, delete, or rename them, mark "Retained in original location (not included in CodeStable system)" in the report. It is absolutely not allowed to move or delete any existing files without confirmation—the reason is simple: the onboarding entry only allows AI to organize, not make deletion decisions on behalf of users; deleting incorrectly has extremely high recovery costs.

Step 6: Reminder about AGENTS.md (same as Step 3 of the empty repository path)

Step 7: Acceptance Report

List:

List of migrated files (from → to)
List of newly created skeleton files
List of non-migrated files (retained in original location)
Next-step suggestions

Skeleton File Templates

The

DESIGN.md

placeholder template and

AGENTS.md

minimal template have been moved to

reference.md

in the same directory. This skill's main body only retains the process and no longer embeds long templates.

Exit Conditions

The

codestable/

directory skeleton is complete (all eight subdirectories exist:

requirements/

architecture/

roadmap/

features/

issues/

compound/

tools/

reference/

)

Shared scripts and reference documents under
```
codestable/tools/
```
and
```
codestable/reference/
```
have been copied from this skill package (sub-skills must be able to read these files during runtime)
```
codestable/architecture/DESIGN.md
```
has been created (even with placeholder content)
Migration path: Each mapping has a clear processing result (migrated / retained in original location)
Migration path: No files were moved without user confirmation
The status of
```
AGENTS.md
```
is clear (exists / user knows it needs to be supplemented)
Acceptance report has been provided, and the user knows which sub-skill to trigger next

Common Pitfalls

Moving or deleting existing files without user confirmation—the core principle of the migration path is that the user makes the final decision, not the AI acting on its own
Filling in the substantive content of AGENTS.md on behalf of the user—the specifications and taboos in AGENTS.md must be determined by the project owner; the AI only provides templates and guidance
Starting a feature/issue immediately after building the skeleton—the responsibility of onboarding is to "set up the environment", not "start working"; it ends after the skeleton is completed
Creating AGENTS.md in
codestable/
—AGENTS.md is a root directory file and does not belong under
```
codestable/
```
Directly executing mappings with low confidence—low confidence = must ask; migrating without asking is making decisions on behalf of the user
Overwriting and rebuilding the entire
codestable/
structure when it exists partially—except for
```
tools/
```
and
```
reference/
```
, files with content are not allowed to be overwritten, only vacancies are supplemented
Adopting a "no overwrite" conservative strategy for
codestable/tools/
and
codestable/reference/
—on the contrary, these two directories must be overwritten with the latest version from the skill package, otherwise the user's project will stay on outdated scripts and standards after skill upgrades
Manually "transferring" file content using Read + Write—must use
```
cp -rf
```
/
```
Copy-Item -Recurse -Force
```
to overwrite the entire directory. Read+Write will truncate long files, eat blank lines, modify indentation, and moving files one by one is easy to miss, slow, and token-consuming
Forgetting to exclude
node_modules/
and
.git/
when globbing—this will fill the scan results with noise and lead to incorrect path judgments

cs-onboard

NPX Install

Tags

SKILL.md Content (Chinese)

cs-onboard

Two Paths

Involved Paths

Standard Skeleton (Target State)

Startup Checks

Empty Repository Path

Applicable Conditions

Execution Steps

Migration Path

Applicable Conditions

Execution Steps

Skeleton File Templates

Exit Conditions

Common Pitfalls

Related Documents