lidge-jun/dev-scaffolding

Dev Scaffolding

C0/C1 work (small local patches): See dev §0.0 Work Classifier + §0.1 Patch Fast-Path before reading references.

dev is canonical: dev §0.2 Rule Classes, §3 Verification Gate, and §5 Safety Rules apply to all work governed by this skill.

Rules for generating and auditing project structures. Create files directly following these rules. Use the audit script (§12) for verification. This skill activates by change surface: new project setup, feature/module scaffolding, structural audits, or documentation scaffolding.

Modular References

| File | When to Read | What It Covers | |------|-------------|----------------| | references/implementation-log.md | C3+/multi-phase/cross-session work units | Full devlog routine: decade-numbered plan folders, P-concretize → A-audit → D-archive loop, mainstream design-doc/RFC mapping | | references/api-docs.md | API documentation generation | OpenAPI 3.1, developer portal, CI doc drift, SDK generation | | references/monorepo-tooling.md | Setting up or optimizing monorepo builds | Turborepo vs Nx 2026 decision table, task graph for AI agents, CI optimization |

External/current scaffolding evidence

For current generator behavior, template commands, package versions, framework recommendations, provider bootstrap docs, or source-sensitive tooling choices, read the active search skill and follow its query-rewrite, source-fetch, and evidence-status rules. Browser fetch/open/text/get-dom/snapshot is used only after candidate URLs exist and the setup claim needs source 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. Public Boundary Export — each feature/package exposes a single public entry point (index.ts, index.js, __init__.py, or Go package) at its boundary; internal convenience barrels are banned (owned by dev-architecture §5)

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/source-of-truth 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/source-of-truth default.

2.1 Lightweight Source of Truth (implementation-unit devlog)

The implementation-unit devlog routine (devlog/_plan/ units — dev-pabcd §3.1, UNIT-RESIDENCE-01) is the DEFAULT for any repo you do development work in — a process rule, not a named style to be requested. Propose the structure/ architecture docs when:

• The repo is immature, undocumented, or inconsistent; or
• The user asks for a durable source-of-truth 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. Also detect optional lightweight source-of-truth files such as CONTEXT.md, CONTEXT-MAP.md, and docs/adr/. Reuse them when present. Do not create them unless the repo already uses that convention or the user approves. Create an ADR only for a decision that is hard to reverse, surprising without context, or has a real tradeoff.

SoT sync (DEFAULT, SOT-SYNC-01): before patching a repo, FIND its general source-of-truth docs first (structure/, architecture.md, INDEX/context docs) and read them; any unit that changes architecture, contracts, or structure patches the SoT doc in the SAME unit (C gate, dev-pabcd §3 C). If the repo has no SoT doc, recommend creating one — once, via the proposal flow above — rather than silently working without a source of truth.

Implementation-unit devlog method:

• Split large work into phase-level documents instead of one huge plan — dependency-ordered (PHASE-SPLIT-01), ALL written to diff-level up front (DIFFLEVEL-ROADMAP-01; both defined in dev-pabcd).
• 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.

Phase document naming uses decade-range prefixes (LEXICO-SPLIT-01). For the canonical table (00–09 research, 10–19 Phase 1, etc.), see dev-pabcd/SKILL.md §3.1 Implementation-Unit Documents — that is the single source of truth.

• Plan unit folder: devlog/_plan/YYMMDD_slug/
• 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. This gate governs INTRODUCING the convention to a repo (the first devlog/ or structure/); once devlog/_plan/ exists, creating unit subfolders — including the minimal record unit mandated by UNIT-RESIDENCE-01 — is routine and needs no approval dialogue.

2.2 Project Skeleton

For a new project, propose the source-of-truth structure in the plan. If the user explicitly asks for the full source-of-truth standard (§8), 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 per-feature public boundary exports (per dev-architecture §5; file names from language 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 | Public boundary export | | ---------- | ------------- | -------------- | -------------- | ---------------------- | | 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 = boundary) | | Rust | kebab-case/ | name.rs | inline #[cfg(test)] or tests/ | lib.rs/parent mod name; |

The index.* file is the feature's public boundary export. Barrel discipline is owned by dev-architecture §5: external consumers import this boundary, internal code imports sources directly, and convenience-only internal barrels are banned.

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_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 standard, not the lightweight default.

Use it when:

• The user explicitly asks for the full Lidge 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 >400 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. Cross-Cutting Scaffolding

This section owns scaffold file placement only. Behavior, policy, and verification come from the owning surface skill (dev-backend, dev-frontend, dev-devops, dev-security).

Health Endpoints

Backend scaffolds should propose health routes (skip if the mature repo already handles health checks per §2):

• src/routes/health.ts (or equivalent) — /health (liveness) and /ready (readiness)
• See dev-backend/references/core/health-checks.md for response format

SEO Boilerplate (Web Projects)

Web project templates should include:

• public/robots.txt with AI crawler allowlist
• Meta tag component with OG defaults
• JSON-LD helper utility
• Sitemap generation (static or dynamic)

CI Template

Generate CI config scaffold:

lint → typecheck → test (unit) → test (integration) → build → deploy (staging)

Security Boilerplate

Generate security scaffolding: CSP headers, CORS config, rate limiting middleware, .env.example with placeholder secrets. See dev-security/SKILL.md for full patterns.

---

11. Documentation Generation

When role=docs or when generating project documentation:

README Generation

1. Read existing structure (§2 Existing Repo First)
2. Generate README with: project purpose, quick start, architecture overview (link to structure/ if present), contribution guide
3. Match tone to project maturity: immature repos get setup-heavy READMEs; mature repos get architecture-heavy ones

API Documentation

1. Scan route files and extract endpoint signatures
2. Generate per-endpoint docs: method, path, params, request/response shape, auth requirements
3. Place alongside code (colocation) or in docs/api/ per project convention

Structure Documentation

1. Generate structure/README.md or update existing structure docs
2. Include: directory tree, module responsibility map, dependency flow
3. Follow source-of-truth conventions (§2.1) when applicable

Devlog Documentation

1. Follow decade numbering (dev-pabcd/SKILL.md §3.1, LEXICO-SPLIT-01): 00-09 research, 10-19 phase 1, etc.
2. Each devlog entry: title, date, what changed, why, evidence paths
3. Cross-reference related devlog entries within the same _plan/ folder

---

12. 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, public boundary exports (dev-architecture §5), devlog presence, .env safety, file length, and AGENTS.md where those apply.

Scaffold Contract (SCAFFOLD-CONTRACT-01, DEFAULT)

Source: sol research (microsoft/apm, HoangNguyen0403/agent-skills-standard).

A scaffold operation must be deterministic and verifiable:

1. Manifest: before generating files, produce a list of files that will be created/modified with their purpose. Show it to the user or record it.
2. Idempotency: running the scaffold twice on the same input should not create duplicates or corrupt existing files.
3. Template provenance: record which template or pattern was used and its version/commit so the scaffold can be reproduced.
4. Dry run: for C3+ scaffolds, offer a dry-run mode that shows what would be created without writing files.

Post-Scaffold Verification (SCAFFOLD-VERIFY-01, DEFAULT)

After scaffolding, verify the result is usable — do not claim done from structural inspection alone:

1. npm install / pip install / equivalent dependency installation succeeds
2. npm run build / cargo build / equivalent build succeeds
3. npm test / pytest / equivalent test suite passes (even if only a smoke test)
4. Linter runs clean (or with only pre-existing warnings)
5. Dev server starts and responds (for web projects)
6. A second scaffold run on the same input does not break the first (idempotency)

Failures in any of these steps mean the scaffold is incomplete. Fix before claiming done.