easysdd-onboarding

Onboard a repository into the easysdd 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, all sub-workflows (feature / issue / compound, etc.) can run directly on it without needing to explain where the directories are.

Two Paths

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

After starting, first perform a scan for automatic judgment, don't let the user choose themselves—they probably don't know what documents are currently in the project. If the scan result is ambiguous (such as only having a README), clearly state the judgment basis and ask the user for confirmation.

Involved Paths

After onboarding is completed, the authoritative version of shared paths and naming conventions is
easysdd/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)

After onboarding is completed, the following skeleton should exist in the repository:

easysdd/
├── architecture/
│   └── DESIGN.md               ← Architecture entry skeleton (placeholder template when first created)
├── features/                   ← Feature aggregation root (empty directory, .gitkeep)
├── issues/                     ← Issue aggregation root (empty directory, .gitkeep)
├── compound/                   ← Unified directory for knowledge accumulation (empty directory, .gitkeep): four types of documents (learning / trick / decision / explore) are distinguished by doc_type + the type segment in the middle of the file name (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 specifications, checklist lifecycle, recommended phase wrap-up
    ├── tools.md                ← Shared script usage reference
    └── maintainer-notes.md     ← Breakpoint recovery, extension points, maintenance rules

AGENTS.md

is in the project root directory, not in
easysdd/
. Onboarding will check if it exists; if not, it will remind the user but will not write it on behalf of the user—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 the subsequent feature / issue / acceptance phases, or explicitly accept that the current warehouse temporarily has no project-level hard constraint entry.

Startup Checks

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

Check if the
easysdd/
directory exists
- Does not exist: Candidate for empty repository path
- Exists but incomplete: Migration path (partial completion)
Glob all
.md
files in the repository (exclude
```
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/
```
- Which files already exist under the existing
```
easysdd/
```
Check if
AGENTS.md
exists (root directory)
Report scan conclusions—explain in one paragraph:
- Which documents possibly related to the easysdd system were found (list file paths)
- Which path is judged to be taken, and the judgment basis
- Which uncertain items need user confirmation

Empty Repository Path

Applicable Conditions

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

Execution Steps

Step 1: Confirm scope with the user

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

Project name / introduction (used to fill in the
```
DESIGN.md
```
placeholder template)
Whether
```
AGENTS.md
```
already exists; if not, whether to fill it in now—if they want to fill it in now, guide them to fill in the key fields; if they want to do it 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 a one-time whole, step-by-step confirmation will disrupt the rhythm:

```
easysdd/architecture/DESIGN.md
```
(fill in the placeholder template, see
```
reference.md
```
in the same directory)
```
easysdd/features/.gitkeep
```
```
easysdd/issues/.gitkeep
```
```
easysdd/compound/.gitkeep
```
```
easysdd/tools/
```
(copy all files under
```
easysdd-onboarding/tools/
```
in this skill package as-is, without modifying the content)
```
easysdd/reference/
```
(copy all files under
```
easysdd-onboarding/reference/
```
in this skill package as-is, without modifying the content—this is the only way all easysdd sub-skills share reference documents during runtime)

Step 3: AGENTS.md Reminder

If there is no

AGENTS.md

in the root directory:

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

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

reference.md

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

Step 4: Acceptance Report

List which files were created, tell the user:

The easysdd skeleton is ready. Now you can:
Start a new feature: Trigger the
easysdd-feature
skill
Report an issue: Trigger the
easysdd-issue
skill
Accumulate knowledge: Trigger the
easysdd-learning
skill

Migration Path

Applicable Conditions

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

easysdd/

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 easysdd Location	Confidence
`docs/DESIGN.md`	Project architecture document	`easysdd/architecture/DESIGN.md`	High
`docs/feature-auth.md`	Design draft of a certain feature	`easysdd/features/YYYY-MM-DD-auth/auth-design.md`	Medium
`SPEC.md`	Functional requirement document?	Need user confirmation	Low
...	...	...	...

Meaning of Confidence:

High: The file content clearly matches the target location semantically (e.g., architecture documents are placed in the architecture directory)
Medium: Can be inferred but has ambiguity (e.g., a document mixes requirements, design, and acceptance together)
Low: The file content is unclear, or it is reasonable to map to multiple locations

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 inference reason and ask "Should it be placed in this way?"
Low confidence: Describe the file content, provide 2-3 candidate locations for the user to select, and provide 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 so that the user has the opportunity to object. The reason is that high-confidence judgments may also be wrong, but asking item by item will disrupt the rhythm—listing them in the report gives the user a review opportunity without interrupting the process.

Step 3: Handle easysdd documents "half-written in the middle"

easysdd/

already partially exists:

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

Step 4: Complete the missing skeleton

Compare with the standard skeleton above, complete the directories and files that are still missing after the user confirms the migration plan. Do not overwrite directories with existing content, only fill in the gaps.

Missing tool files under

easysdd/tools/

are completed from the corresponding

easysdd-onboarding/tools/

in this skill package; existing files are not overwritten (users may have modified them).

Missing reference documents under

easysdd/reference/

are completed from the corresponding

easysdd-onboarding/reference/

in this skill package; existing files are not overwritten (users may have modified them). If there is a file with the same name in the project but the content is different from that in the skill package, prompt the user once ("This file in the project is inconsistent with the current skill package, do you need me to list the differences?"), but do not overwrite it for them—reference is a shared specification read by all sub-skills, and the cost of overwriting is high.

Step 5: Handle files that are not migrated

Files that the user chooses to "Skip": Do not move, delete, or rename them, mark "Keep in original location (not included in the easysdd 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 to make deletion decisions on behalf of the user, and the recovery cost is extremely high if deleted by mistake.

Step 6: AGENTS.md Reminder (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 (kept in original location)
Next-step suggestions

Skeleton File Templates

The

DESIGN.md

placeholder template and the minimal

AGENTS.md

template have been split into

reference.md

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

Exit Conditions

The
```
easysdd/
```
directory skeleton is complete (all six sub-directories exist:
```
architecture/
```
,
```
features/
```
,
```
issues/
```
,
```
compound/
```
,
```
tools/
```
,
```
reference/
```
)
Shared scripts and reference documents under
```
easysdd/tools/
```
and
```
easysdd/reference/
```
have been copied from this skill package (sub-skills must be able to read these files during runtime)
```
easysdd/architecture/DESIGN.md
```
has been created (even if it's placeholder content)
Migration path: Each mapping has a clear processing result (migrated / kept 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 completed)
The 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 to "start working", it ends after the skeleton is completed
Creating AGENTS.md in
easysdd/
—AGENTS.md is a root directory file and does not belong under
```
easysdd/
```
Directly executing mappings with low confidence—low confidence = must ask, migrating without asking is making judgments on behalf of the user
Reconstructing all existing partial
easysdd/
structures by overwriting—files with content are not allowed to be overwritten, only gaps are filled
Forgetting to exclude
node_modules/
and
.git/
when globbing—this will fill the scan results with noise and lead to wrong path judgments

easysdd-onboarding

NPX Install

Tags

SKILL.md Content (Chinese)

easysdd-onboarding

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