Ywc Project Scaffold

---
name: ywc-project-scaffold
version: 1.0.0
description: "(ywc) Use when the user wants to scaffold a new project structure, design a folder layout, or organize files for a specific tech stack. Triggers: 'project structure', 'scaffold a new project', 'folder layout', 'project skeleton', '프로젝트 구조', 'プロジェクト構成', a language/framework combined with 'structure' or 'scaffold', or reviewing this skill's `references/<language>.md` (e.g. 'review go.md', 'refresh the python reference'). Do not use for modifying an existing structure, generating individual files, creating tasks (use ywc-task-generator), surveying a repo to generate its CLAUDE.md (use ywc-onboard-repo), or generic documentation review."
category: spec
phase: planning
requires: []
advisor_budget: 0
allowed tools: Read, Write, Edit
---

# Project Scaffold - Directory Structure Generator

**Announce at start:** "I'm using the ywc-project-scaffold skill to design a directory structure tailored to the chosen tech stack."

Generate well-organized project directory structures in Markdown, tailored to specific tech stacks, architecture patterns, and project requirements.

## Rationalization Defense

When tempted to skip a step, check this table first:

| Excuse | Reality |
|---|---|
| "Tech stack not specified, assume Node + TypeScript" | Always ask for language + framework + scale. Wrong-stack scaffolds are useless. |
| "Architecture pattern is implicit" | Make it explicit (layered / hexagonal / clean / DDD / etc.). The choice cascades through every directory. |
| "Skip the rationale per directory, just emit the tree" | Each non-obvious directory needs a one-line purpose. Trees without rationale invite misuse. |
| "Generate actual files instead of a Markdown plan" | This skill is for plan only. File generation belongs to ywc-code-gen. |
| "Project scale guessed at 'medium', do not ask" | Scale (small / medium / large / monorepo) changes the structure significantly. Always ask. |
| "Add every conceivable directory for completeness" | Over-scaffolding creates empty noise. Include only directories with a current purpose. |
| "Reference file is good enough, skip the trend check for a large-scale request" | `references/*.md` are hand-maintained and can lag current practice. Large scale or a contested Architecture choice warrants a lightweight `/ywc-tech-research` check before finalizing (see Trend check in step 2). |
| "User wants a reference file updated, just edit it directly" | Reference-file review/refresh requests propose an additive diff for approval first (see Reference Refresh, step 6). Silent edits change every future scaffold call using that language. |

**Violating the letter of these rules is violating the spirit.** A scaffold that does not match the user's actual stack becomes immediate technical debt.

## Triggers

- New project initialization with a specific tech stack
- Directory structure design for language + framework + protocol combinations
- Project restructuring or refactoring of folder layout
- "Create a project structure with this stack", "scaffold a FastAPI project"
- Reference file audit/refresh request — "review go.md", "refresh the python reference with current trends", "re-audit this reference against recent practice"

## Usage

```
/ywc-project-scaffold [description]
```

**Examples:**
```
/ywc-project-scaffold FastAPI + GraphQL + Clean Architecture, medium scale
/ywc-project-scaffold Rails API with gRPC, large scale e-commerce
/ywc-project-scaffold NestJS + WebSocket + DDD, small scale chat app
/ywc-project-scaffold Go microservice with gRPC and event-driven
```

## Input Analysis

Identify the following elements from user input. Language, Framework, and Scale are never defaulted — always ask (see Rationalization Defense). Architecture, Protocol, and Domain may fall back to the listed default when unspecified.

| Element | Example | Default |
|---------|---------|---------|
| **Language** | Python, Ruby, Go, Rust, JavaScript, TypeScript | Required — always ask |
| **Framework** | FastAPI, Rails, NestJS, Next.js, Astro, Gin, Echo | Required — always ask |
| **Architecture** | Clean Architecture, Hexagonal, DDD, MVC, Layered | Follows Framework conventions |
| **Protocol** | REST API, GraphQL, gRPC, WebSocket, Message Queue | REST API |
| **Scale** | small, medium, large | Required — always ask |
| **Domain** | e-commerce, SaaS, chat, CMS, etc. | General-purpose |

### Scale Criteria

- **Small**: Single service, small team (1-3 members), rapid MVP
- **Medium**: Modularized service, mid-size team (3-8 members), typical production
- **Large**: Multi-module/Monorepo consideration, large team (8+ members), enterprise-grade

## Behavioral Flow

### 1. Analyze - Parse and Confirm Input

Extract the above elements from user input. If there are ambiguous parts, briefly confirm with the user.

### 2. Load References - Load Relevant References

Read language-specific Reference files and refer to the structure matching the given Framework and Architecture.
If the Protocol is not REST, also refer to `references/protocols.md`.

- Python/FastAPI → `references/python.md`
- Ruby/Rails → `references/ruby.md`
- JavaScript/TypeScript (Next.js, NestJS, Astro) → `references/javascript.md`
- Go (Gin, Echo, standard) → `references/go.md`
- Rust (Actix Web, Axum, standard) → `references/rust.md`
- Protocol related → `references/protocols.md`

**Fallback (no matching reference)**: if the requested language or framework has no matching reference file above, proceed using general project-structure principles and confirm the stack assumptions with the user before generating.

**Compound condition handling**: Combine multiple References. For example, for "FastAPI + GraphQL", refer to both `python.md` and `protocols.md` to generate an integrated structure.

**Trend check (conditional)**: The loaded reference is a fast, curated baseline, not a permanent verdict — it is hand-maintained and can lag current practice. When Scale is `large`, or the user explicitly contests/questions the Architecture choice, pause and delegate to `/ywc-tech-research "<language>/<framework> project structure conventions" --depth 25` before finalizing the tree. Compare its findings against the loaded reference:

- If findings confirm the reference, proceed without comment.
- If a material delta exists (a convention the reference is missing, or one that has since shifted), surface it as a labeled callout in step 5 (Extras) — do not silently substitute it into the tree, and do not edit the reference file from this step (that is Reference Refresh, step 6, below).

Skip this sub-step for `small`/`medium` scale with an uncontested Architecture — the static reference is sufficient and the research overhead is not justified for a fast baseline case.

### 3. Generate - Create Directory Structure

Generate Markdown in the following format:

```markdown
# [Project Name] Directory Structure

> **Stack**: [Language] + [Framework] + [Protocol]
> **Architecture**: [Pattern]
> **Scale**: [small/medium/large]

## Directory Structure

\```
project-root/
├── src/                          # Application source code
│   ├── domain/                   # Domain layer - business logic
│   │   ├── models/               # Domain entities and value objects
│   │   └── services/             # Domain services (pure business rules)
│   ├── application/              # Application layer - use cases
│   │   ├── commands/             # Write operations (CQRS)
│   │   └── queries/             # Read operations
│   ...
\```

## Key Directory Descriptions

### `src/domain/`
The domain layer is the core of business logic. It contains only pure business
rules without any Framework or external dependencies.

**Reason for this structure**: In [Architecture Pattern], the domain is ...

### `src/infrastructure/`
...
```

### 4. Explain - Describe the Structure

Explain the following for each major Directory:

- **Role**: The responsibility this Directory handles
- **Reason for this structure**: Why it is organized this way according to the Architecture Pattern or Framework conventions
- **Example files included**: 1-2 representative files
- **Dependency direction**: Which Layer it references and which Layer references it (when an Architecture Pattern is applied)

### 5. Extras - Additional Guidance (if needed)

Provide useful additional information based on the project domain or scale:

- Explanation of key configuration files (e.g., `pyproject.toml`, `Gemfile`, `go.mod`)
- Framework-specific convention notes
- Structural changes to consider when scaling up

### 6. Reference Refresh - Optional Mode

Triggered when the user asks to review, refresh, or audit a `references/<language>.md` file itself, rather than generate a project plan. This mode never edits silently — it produces a proposal for the user to approve, then stops.

1. **Identify target(s)** — the `references/<language>.md` file(s) named or implied by the request. Language is inferred from the matched file path, not asked for separately; Framework and Scale (required elsewhere in this skill) do not apply to this mode.
2. **Gather evidence**: if the user supplies a real-world repository or documentation path to cross-check, read/grep it directly and compare its actual structure against the reference. Otherwise, delegate to `/ywc-tech-research "<language> project structure best practices"` (or `"<language>/<framework> project structure best practices"` when Framework is known), with `--depth 25`.
3. **Diff against the current reference** — identify genuinely new or divergent patterns, not just rephrasing of what is already documented.
4. **Propose additively** — a new variant section alongside existing ones, or new rows in an existing Conventions/Key Points table. Never delete or silently overwrite an existing documented pattern; an older pattern may still be a valid alternative for a different context (see how `Go Large (DDD)` and `Go Large (Layered, Connect RPC)` coexist as sibling variants in `references/go.md`).
5. **Present the diff and stop** — show the proposed addition to the user and wait for approval before editing. After approval, apply the edit and run the project's Markdown lint check on the touched file(s) before reporting done.

## Output Rules

- Use `├──`, `└──`, `│` characters for tree format
- Add inline comments (`# description`) next to each Directory/File
- If the description is long, separate it into a dedicated section below
- Avoid unnecessarily deep nesting (4+ levels); show detail only when necessary
- Prioritize official language/Framework conventions when they exist (e.g., Rails `app/`, Go `cmd/`)
- Do not generate Docker, CI/CD, Kubernetes, or Deployment-related Directories (`Dockerfile`, `docker-compose`, `.github/`, `deployments/`, `k8s/`, etc.). Focus only on Application Source Code structure

## Boundaries

**Will:**
- Generate Directory structures optimized for language + Framework + Protocol + Architecture combinations
- Explain the role and rationale behind each Directory
- Reflect structural differences based on Scale
- Support compound conditions (e.g., FastAPI + GraphQL + DDD)
- Audit/refresh a `references/<language>.md` file against real-world evidence or `/ywc-tech-research` findings, proposing an additive diff for approval (Reference Refresh, step 6)

**Will Not:**
- Generate actual Code file contents (only provides structure)
- Generate Boilerplate Code (use `/sc:implement` for implementation)
- Configure Docker, CI/CD, or Monorepo setup (provide guidance upon separate request)
- Move, rename, or edit files in the user's target project (this skill is plan-only there) — the sole exception is Reference Refresh (step 6) editing this skill's own `references/<language>.md` file, and only after the user approves the proposed diff
- Auto-apply a reference-file edit without user confirmation
- Remove or overwrite an existing documented variant during Reference Refresh — that mode stays additive-only