Ywc Project Scaffold

---
name: ywc-project-scaffold
description: >-
  (ywc) Use when designing a new project's directory structure or architecture
  skeleton before files are generated. Triggers: "project structure", "scaffold
  a new project", "folder layout", "프로젝트 구조", "디렉토리 구조", "プロジェクト構成",
  "フォルダ構成", or reviewing this skill's `references/<language>.md`. Do not
  use for generic documentation review, existing repo changes, file generation
  (use ywc-code-gen), task creation (use ywc-task-generator), or onboarding
  (use ywc-onboard-repo).
---

# 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. |
| "Run a Trend Check for every scaffold" | Trend Check is conditional: run it only for large or explicitly contested architecture requests. |
| "Refresh a shared reference in place" | Reference refresh is proposal-first. Show an additive diff and wait for explicit approval before editing the skill-owned reference. |

**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
- Planning a not-yet-created folder layout before implementation begins
- "Create a project structure with this stack", "scaffold a FastAPI project"

## Usage

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

**Examples:**
```text
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. Ask a focused clarification when language, framework, or scale is missing; use defaults only for protocol and domain when the user does not care.

| Element | Example | Default |
|---------|---------|---------|
| **Language** | Python, Ruby, Go, Rust, JavaScript, TypeScript | Required |
| **Framework** | FastAPI, Rails, NestJS, Next.js, Astro, Gin, Echo | Recommended by language |
| **Architecture** | Clean Architecture, Hexagonal, DDD, MVC, Layered | Follows Framework conventions |
| **Protocol** | REST API, GraphQL, gRPC, WebSocket, Message Queue | REST API |
| **Scale** | small, medium, large | medium |
| **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

## Modes

### `reference-refresh`

Use this separate mode only when the user asks to review, refresh, or audit one
or more of this skill's own `references/<language>.md` files. Do not route generic
documentation review here. Identify each target path and infer its language from
the filename. If no target can be resolved, return `NEEDS_CONTEXT`.

1. Read the current target reference and use any supplied repository or official
   documentation evidence directly. If no real-world evidence is supplied,
   delegate a focused `ywc-tech-research --depth 25` check. Use a language-only
   topic when the framework is unknown; include the framework only when it is
   known.
2. Compare the evidence with the current reference. Exclude rephrasing and
   patterns already documented. Keep existing alternatives and valid variants.
3. Produce an additive proposal: a sibling variant or entries in an existing
   conventions/key-points section. Display the proposed diff and return it in
   `Mode: reference-refresh`.
4. Stop after the proposal for the current turn and wait for explicit user
   approval. Only a later approved turn may edit these skill-owned reference
   files, followed by Markdown lint and structural validation.

This is the only write exception to the normal project boundary, and it applies
only to this skill's own references after approval. It never edits the user's
target project, silently rewrites a reference, removes a valid variant, or
creates project files.

## 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.

### 2.5 Trend Check - Conditional Current-Practice Comparison

After loading the relevant references and before finalizing the tree, run a
focused Trend Check when either the requested scale is `large` or the user
explicitly questions or contests the requested/selected architecture. Delegate
the topic (for example, `<language>/<framework> project structure conventions`)
to `ywc-tech-research --depth 25`.

- If the findings confirm the loaded baseline, continue without extra prose.
- If they show a material delta, retain the loaded baseline and add a clearly
  labelled `Extras` callout describing the delta and its source.
- If research is unavailable or inconclusive, retain the baseline and report
  `DONE_WITH_CONCERNS` with the evidence gap; do not invent a trend.

Never silently substitute research findings into the tree or edit a reference.
Explicitly skip this branch for uncontested small and medium requests.

### 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

## 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
- In `reference-refresh` mode, return the additive proposal and displayed diff
  with `Mode: reference-refresh`; the approval stop is terminal for the current
  turn and is not a completed edit.

## 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)

**Will Not:**
- Generate actual Code file contents (only provides structure)
- Generate Boilerplate Code (use `ywc-code-gen` for implementation)
- Configure Docker, CI/CD, or Monorepo setup (provide guidance upon separate request)
- Silently apply Trend Check findings, edit references without approval, remove
  existing reference variants, or route generic documentation review

## Output Format

Return the scaffold recommendation as a structured report:

```text
Status: <DONE | DONE_WITH_CONCERNS | BLOCKED | NEEDS_CONTEXT | AWAITING_APPROVAL>
Mode: <scaffold | reference-refresh>
Scaffold: <tree or named structure>
Rationale: <language / framework / architecture decisions>
Boundaries: <what is intentionally excluded>
Validation: <checks against requested stack and constraints>
Next action: <implementation handoff | approval required | "none">
```

`reference-refresh` returns `Status: AWAITING_APPROVAL` and `Next action: approval required` after step 3's proposal — never `DONE` before the user has approved the edit.

## Common Mistakes

- Running Trend Check for every request instead of only for large or explicitly
  contested architecture decisions.
- Treating current-practice research as permission to rewrite the loaded
  baseline or silently alter the generated tree.
- Editing a shared reference during `reference-refresh` before the user approves
  the additive proposal and displayed diff.

## Validation

Before finalizing, verify that the scaffold matches the requested language, framework, protocol, architecture, and scale; contains no generated code or deployment assets; avoids unnecessary depth; and explains each major directory's role and dependency direction.
For `reference-refresh`, also verify that targets are skill-owned, the proposal
is additive, existing valid variants remain intact, and the current turn stops
after displaying the diff until explicit approval.