dev-scaffolding

name	dev-scaffolding
description	Scaffold new projects or add feature modules following the Lidge Standard (Feature-based + Colocation + Barrel Export + devlog). Language-agnostic — auto-detects project type from config files. Also audits existing projects for structural compliance. Triggers: scaffold, new project, new feature, init project, audit structure, scaffolding, add module, project setup.

Dev Scaffolding

Rules for generating and auditing project structures. Create files directly following these rules. Use the audit script (§10) for verification.

1. The Lidge Standard

Apply for new projects or when a repo has no clear structural convention of its own; defer to an existing mature convention when one is present (§2). Three pillars:

1. Screaming Architecture — folder names reveal what the app does (stock-price/, auth/, report/)
2. Colocation — related files live together (logic + test + schema in the same folder)
3. Barrel Export — each feature exposes a single entry point (index.ts, index.js, __init__.py, or Go package)

2. Existing Repo First

Before scaffolding inside an existing repo:

1. Detect existing architecture, docs, plans, changelog, ADR, agent-context, source-of-truth, and devlog conventions.
2. Read existing structure/, devlog/, docs/, plans/, or equivalent source-of-truth logs before proposing new structure.
3. Reuse clear conventions instead of imposing the Lidge/Jawdev default.
4. Show a compact tree before broad additions.
5. Do not create structure/, devlog/, docs/, AGENTS.md, or similar project-level folders without approval.

MUST preserve mature repo conventions over the Lidge/Jawdev default.

2.1 Lightweight Jawdev Source of Truth

Use this only when:

• The repo is immature, undocumented, or inconsistent; or
• The user asks for Jawdev/Lidge-style structure; or
• A broad change needs a durable plan/current-architecture record.

Default proposal:

structure/
  README.md              # index of current architecture docs
  architecture.md        # current system shape, not future wishes
  conventions.md         # naming, layout, commands, testing
devlog/
  _plan/                 # active plans
  _fin/                  # completed work summaries

Folder names are advisory. If the repo already has docs/, adr/, plans/, changelog/, or another convention, propose using those instead.

Jawdev devlog method:

• Split large work into phase-level documents instead of one huge plan.
• Keep diff-level plans in files, not chat: exact paths, NEW/MODIFY/DELETE, before/after diffs for MODIFY, complete content for NEW.
• Keep chat summaries short: explain the phase, show a compact tree/change map, then link the plan file.
• Move completed phase folders to _fin/; keep pending/future work under _plan/ or an existing equivalent.

Jawdev phase document naming uses decade-range prefixes (see dev-pabcd/SKILL.md for the canonical table):

• Plan unit folder: devlog/_plan/YYMMDD_slug/
• 00–09 research/specs/MOC (mandatory before implementation), 10–19 Phase 1, 20–29 Phase 2, and so on.
• Default sequential within a decade (00, 01, 02…); on overflow use a sub-index (00_0_name.md, 00_1_name.md).
• 00_* (e.g. 00_plan.md or 00_overview.md) is the plan-folder index and file map.
• The numeric prefix is the source of ordering. Never use bare semantic filenames (PLAN.md, DIFF_PLAN.md, PHASES.md, RCA.md).
• When adding a document, scan siblings and choose the next unused prefix in the correct decade.

Before creating any structure//devlog/ folders, ask concisely: state that no source-of-truth docs were found, show the proposed tree, give a specific recommendation, and confirm you will not create them without approval.

2.2 Project Skeleton

For a new project, propose the source-of-truth structure in the plan. If the user explicitly asks for Lidge/Jawdev standard, create it. Otherwise ask once before adding structure/ and devlog/.

When creating an approved new project skeleton, include the source-of-truth and feature-based essentials: AGENTS.md + README.md (context/overview), .env.example + .gitignore, devlog/_plan/ + devlog/_fin/ (and str_func/ only for the full standard, §8), src/ with a shared/ for truly-shared code, config/, docs/, and tests/e2e/. Then add the language-appropriate package manifest, entry point, language config, and shared barrel from detection (§3). Defer exact layout to the framework's own generator when one exists.

3. Language Detection

Detect project type from existing files. Priority order:

File Found	Project Type
tsconfig.json	TypeScript (Node)
package.json (no tsconfig)	JavaScript (Node)
pyproject.toml or requirements.txt	Python
go.mod	Go
Cargo.toml	Rust
None of the above	→ Tech Stack Decision (below)

For greenfield projects, use the Tech Stack Decision process (§3.1) instead of asking "What language?"

3.1 Tech Stack Decision (New Projects)

When creating a new project with no existing framework, guide the user through plain-language choices:

1. Type: What are they building? (static site, interactive app, full-stack service, CLI tool, data pipeline)
2. Scale: How big? (1-3 pages, multi-page, ongoing content, large app)
3. Features: Login needed? Data storage? Real-time?

Present options as <Framework> — <what it gives you>, recommend one with reasoning, let user pick.

Match tool complexity to task complexity. Escalate tooling only when justified by user requirements (SEO, CMS, scaling).

4. Fullstack Split Rule

Decide project layout based on runtime:

Scenario	Layout	Example
Single runtime	src/ modular	Next.js, Node CLI + API, Python monolith
Multiple runtimes	frontend/ + backend/	React + FastAPI, Vue + Go API
Monorepo (3+ apps)	packages/ or apps/	Turborepo, Nx

Each side gets its own package manifest and entry point. Shared types go in root shared/ or packages/shared/.

5. Feature Module Rules

When adding a new feature, create a folder under src/ with these files:

Language	Folder	Main File	Test File	Barrel
JavaScript	kebab-case/	name.tool.js	name.test.js	index.js
TypeScript	kebab-case/	name.tool.ts	name.test.ts	index.ts
Python	kebab-case/	name_tool.py	test_name.py	__init__.py
Go	kebab-case/	name.go	name_test.go	(package = barrel)
Rust	kebab-case/	mod.rs	name_test.rs	mod.rs

Principle: "flat until you can't" — start flat, sub-folder only when a folder becomes hard to scan.

6. Naming Conventions

Item	Rule	Example
Folders	kebab-case	stock-price/, user-auth/
JS/TS files	kebab-case + suffix	stock-price.tool.ts
Python files	snake_case + suffix	stock_price_tool.py
Go files	snake_case	stock_price.go
Rust files	snake_case	stock_price.rs
devlog plan folders	YYMMDD_slug/	260510_jawdev_phase_doc_naming/
devlog phase docs	decade-prefixed NN_slug.md, 00_* is the index	00_plan.md, 10_phase1_skill_contract.md
Functions (JS/TS)	camelCase	getStockPrice()
Functions (Python)	snake_case	get_stock_price()
Functions (Go)	PascalCase (exported)	GetStockPrice()
Functions (Rust)	snake_case	get_stock_price()

7. File Suffixes

Suffix	Role	Languages
.tool.ts / .tool.js / _tool.py	Core business logic	JS/TS/Python
.test.ts / .test.js / test_*.py / _test.go	Tests	All
.schema.ts / .schema.js	Type/schema definitions	JS/TS
.route.ts / .route.js	API routes	JS/TS
.template.md	Templates	All

8. str_func Rules

str_func is part of the full Lidge/Jawdev standard, not the lightweight default.

Use it when:

• The user explicitly asks for full Lidge/Jawdev structure.
• The repo already maintains str_func docs.
• A broad feature needs durable module-level function documentation.

When used:

• One .md file per feature folder (e.g., price.md, auth.md)
• Keep each document concise, bounded, and task-oriented — not padded to a fixed length
• Required sections: File Tree, Module Responsibility, Key Function Signatures, Dependencies, Dependents, Sync Checklist
• Update the corresponding .md whenever a feature is added or modified
• Template: <SKILL_DIR>/assets/str_func_template.md

Do not generate heavy feature docs by default for small or immature repos. Prefer lightweight structure/architecture.md and structure/conventions.md first.

9. Split Rules

Split smells (heuristics, not hard gates):

Condition	Action
File grows past ~500 lines	Split into focused modules within same folder
Folder becomes hard to scan	Create sub-folders by responsibility
Different runtime needed	Split into frontend/ + backend/
3+ apps share code	Extract to shared/ or monorepo packages/

10. Audit

Run the scaffold audit if one is available for the repo (e.g. bash <SKILL_DIR>/scripts/scaffold-audit.sh [project-path]) to check structural compliance. Audit checks should reflect the project's own conventions — covering feature-based structure, colocation, barrel exports, devlog presence, .env safety, file length, and AGENTS.md where those apply.