Cli Forge Tree

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

| Rule | Example | |------|---------| | lowercase-kebab-case for folders & files | api-gateway/, user-service.ts | | UPPER_CASE only for root meta-files | README.md, LICENSE | | dot-prefix for config/hidden files | .env, .gitignore | | Max 3 levels before needing justification | src/api/handlers/ ok, deeper = rethink | | Descriptive, short, no redundancy | docs/ not documentation-files/ | | Plural for collections | tests/, scripts/ |

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:

| Signal | Archetype | |--------|----------| | Cargo.toml | rust | | go.mod | go | | package.json | js/ts | | pyproject.toml / setup.py | python | | *.tf | terraform | | Chart.yaml / helmfile.yaml | helm | | kustomization.yaml | kustomize (check for flux-system/ → flux) | | Containerfile / Dockerfile | oci-container | | *.container / *.kube | podman-quadlet | | site.yml / playbooks/ / roles/ | ansible | | docker-compose*.yml | docker-compose | | *.sh + no other code | shell-scripts | | flake.nix | nix | | Multiple of the above | monorepo |

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

| # | Item | Weight | What to check | |---|------|--------|---------------| | 1 | Naming consistency | 5 | All folders follow same convention | | 2 | Depth control | 4 | No folder deeper than 4 levels without justification | | 3 | Standard files present | 4 | README, LICENSE, .gitignore exist at root | | 4 | Archetype fit | 3 | Structure matches detected language/framework conventions | | 5 | Separation of concerns | 4 | Source, tests, docs, config in distinct locations | | 6 | No orphan files | 3 | No loose files in wrong directories | | 7 | Entry point clarity | 3 | Main/index file is obvious | | 8 | Test colocation | 2 | Tests near or mirroring source structure |

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

| Condition detected | Recommend | Why | |-------------------|-----------|-----| | Files in wrong directories | /cli-audit-sync | Check if docs reference old paths | | No CONTRIBUTING.md found | /cli-forge-doc | Generate contributing guide | | Deep nesting detected | /cli-audit-tangle | Check if structure reflects code coupling |

Rule: Recommend, don't auto-execute.

Integration with other cli-* skills

| Skill | Relation | |-------|----------| | /cli-forge-readme | Feed the "Project Structure" section of the README | | /cli-forge-doc | Reference structure for generating the docs | | /cli-audit-tangle | Compare the physical structure against the logical couplings | | /cli-audit-code | Verify naming conventions aligned with the structure | | /cli-forge-chef | Assign worktrees based on the structure | | /cli-cycle | Included in the cycle's structural audit |

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: Destynova2
• Source: Destynova2/cli-code-skills
• License: MIT

Install and usage instructions live in the source repository linked above.