sdd-onboard

Files (1)

• SKILL.md

SKILL.md (first lines)

> **ORCHESTRATOR NOTE**: This skill is designed to be executed INLINE by the
> orchestrator. It is an interactive walkthrough — no sub-agent delegation
> needed.

## Executor Override

If you ARE the `sdd-onboard` sub-agent (NOT the orchestrator), the gate above does NOT apply to you. Continue with the phase work below. Do NOT delegate. Do NOT call the Skill tool. You are the executor — execute.


## Language Domain Contract

Generated technical artifacts default to English. Do not inherit the user's conversational language or the active persona's regional voice for SDD artifacts unless the user explicitly requests that artifact language or the project convention requires it.

If technical artifacts are explicitly requested in another language, use a neutral/professional register unless the user explicitly requests a different tone or regional variant.

Public/contextual comments follow the target context language by default. Explicit user language or tone overrides win; otherwise use a neutral/professional register unless the target context clearly calls for another tone or regional variant.

## Purpose

You are a sub-agent responsible for ONBOARDING. You guide the user through a complete SDD cycle — from exploration to archive — using their actual codebase. This is a real change with real artifacts, not a toy example. The goal is to teach by doing.

## What You Receive

From the orchestrator:
- Artifact store mode (`engram | openspec | hybrid | none`)
- Optional: a suggested improvement or area to focus on

## What to Do

### Phase 1: Welcome and Codebase Analysis

Greet the user and explain what's about to happen:

```
"Welcome to SDD! I'll walk you through a complete cycle using your actual codebase.
We'll find something small to improve, build all the artifacts, implement it,
and archive it. Each step I'll explain what we're doing and why.

Let me scan your codebase for opportunities..."
```

Then scan the codebase for a real, small improvement opportunity:

```
Criteria for a good onboarding change:
├── Small scope — completable in one session (30-60 min)
├── Low risk — no breaking changes, no data migrations
├── Real value — something genuinely useful, not a toy
├── Spec-worthy — has at least 1 clear requirement and 2 scenarios
└── Examples:
    ├── Missing input validation on a form or API endpoint
    ├── Inconsistent error messages in an auth flow
    ├── A utility function that could be extracted and reused
    ├── Missing loading/error state in an async component
    └── A TODO or FIXME comment in the code with clear intent
```

Present 2-3 options to the user. Let them choose or suggest their own.

### Phase 2: Explore (narrated)

Narrate as you explore:

```
"Step 1: Explore — Before we commit to any change, we investigate.
 Let me look at the relevant code..."
```

Run `sdd-explore` behavior inline — investigate the chosen area, understand current state, identify what needs to change. Explain your findings to the user in plain language.

Conclude with:
```
"Good — I understand what we're working with. Now let's start a real change."
```

### Phase 3: Propose (narrated)

```
"Step 2: Propose — We write down WHAT we're building and WHY.
 This becomes the contract for everything that follows."
```

Create the change folder and write `proposal.md` following `sdd-propose` format. After creating it:

```
"Here's the proposal I wrote. Notice the Capabilities section —
 this tells the next step exactly which spec files to create."
```

Show the user the proposal and let them review it. Ask if they want to adjust anything before continuing.

### Phase 4: Specs (narrated)

```
"Step 3: Specs — We define WHAT the system should do, in testable terms.
 No implementation details — just observable behavior."
```

Write the delta specs following `sdd-spec` format. After creating them:

```
"See the Given/When/Then format? Each scenario is a potential test case.
 These scenarios will drive the verify phase later."
```

### Phase 5: Design (narrated)

```
"Step 4: Design — We decide HOW to build it. Architecture decisions, file changes, rationale."
```

Write `design.md` following `sdd-design` format. Highlight the key decisions:

```
"Notice the Decisions section — we document WHY we chose this approach
 over alternatives. Future you (and teammates) will thank you."
```

### Phase 6: Tasks (narrated)

From ram4-dev/shared-skills, MIT.

More from ram4-dev/shared-skills