Optimization: This skill uses on-demand loading. Heavy content lives in references/ and is loaded only when needed.

Language rule: Skill instructions are written in English. When generating user-facing output, detect the project's primary language (from README, comments, docs, commit messages) and produce the output in that language. If the project is bilingual, ask the user which language to use before proceeding.

Project Tree — Structure & Scaffold

Visualize, audit, or scaffold project directory structures with human-readable naming that any skill level can navigate.

Core Principles

• Read `../gotchas.md` before producing output to avoid known pitfalls.

Core Conventions (Summary)

Read references/conventions.md for detailed naming rules, depth guidelines, and cross-cutting folders.

Exceptions: Follow ecosystem conventions when universal (Cargo.toml, package.json, __init__.py, lib.rs).

Workflow

Step 1 — Detect or Ask

If a project exists — read the root directory and detect archetype:

Then: display the current tree (annotated), highlight issues, suggest improvements.

If no project or empty directory — use ask_user_input QCM:

• Q1: "What are you building?" (Library, CLI, API, Infra, Full-stack, Monorepo, Other)
• Q2: "Primary language/stack?"
• Q3: "Extras to include?" (Docker, CI/CD, Docs, Nix, Benchmarks, Examples)

Step 2 — Generate or Audit

Generate mode (new project): Read references/archetypes.md for the full template matching the detected archetype. Scaffold using mkdir -p and touch for placeholder files.

Audit mode (existing project): display annotated tree, then list naming violations, missing standard files, suggested reorganization.

Step 3 — Display

Always show the tree in annotated format:

project-name/
├── src/                    # Source code
│   ├── lib.rs              # Library entry point
│   └── handlers/           # Request handlers
├── tests/                  # Integration tests
├── docs/                   # Documentation
├── Cargo.toml              # Manifest & deps
├── README.md               # Project landing page
└── .gitignore              # Git exclusions

Annotation rules:

• Every folder gets a # comment — 3-6 words max
• Files only get comments if their role isn't obvious from the name
• Use the exact ├── / └── / │ box-drawing characters
• Max 2 levels shown by default. Deeper = collapsed with ...

Quality Scoring — Structure Health Score (SHS)

SHS Formula

SHS = Σ(wᵢ × sᵢ) / Σ(wᵢ) × 10

Checklist Items

Scoring: 0.0 = absent/violated, 0.25 = poor, 0.5 = inconsistent, 0.75 = good, 1.0 = excellent

Thresholds: 8+ clean, 6-8 minor issues, 4-6 needs reorganization, <4 structural problems

Output the SHS table at the end of the tree analysis.

Output

• Visualize: always show the annotated tree in conversation
• Scaffold: create directories and placeholder files on the filesystem
• Audit: list issues + suggested fixes, then show the "ideal" tree side-by-side
• If the readme skill is also being used, feed the annotated tree into Tier 3 "Project Structure"

Dynamic Handoffs

Rule: Recommend, don't auto-execute.

Integration with other cli-* skills