lidge-jun/dev-scaffolding

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.