scaffolding

name	scaffolding
description	Generate project scaffolds and boilerplate.

Scaffolding

Generate new code structures that match existing codebase conventions. Detect patterns first, then produce consistent output.

Core principle: Never generate from generic templates. Always derive from what already exists in the project.

When to Use

• Creating a new module, service, component, or package in an existing codebase
• Setting up a new project that should follow team conventions
• Adding boilerplate that must match surrounding code style

Not for: one-off scripts, exploratory prototypes, or codebases without established patterns.

Process

1. Detect  — Scan existing code for conventions (structure, naming, imports, patterns)
2. Match   — Identify which convention set applies to the new code
3. Generate — Produce scaffold matching detected conventions
4. Verify  — Run lint, typecheck, and any project-specific validation

1. Detect Conventions

Before generating anything, analyze the codebase:

# Directory structure patterns
ls -la src/modules/  # or components/, services/, packages/

# File naming conventions
# kebab-case? PascalCase? index.ts barrels?

# Import patterns
# Absolute vs relative? Path aliases? Barrel exports?

# Test co-location
# __tests__/? *.test.ts beside source? test/ directory?

Look for:

• Naming: file names, directory names, export names
• Structure: file organization within a module, barrel exports, index files
• Patterns: dependency injection, factory functions, class vs functional
• Config: per-module config files, environment handling
• Tests: location, naming, setup patterns, fixtures

2. Match Conventions

Find the closest existing example to what you are creating. Use it as the template — not a generic scaffold.

# Find the most recently created module as reference
ls -lt src/modules/ | head -5

# Read its structure
ls -R src/modules/existing-module/

3. Generate

Produce files matching the detected patterns. Include:

• Directory structure matching siblings
• Boilerplate files with correct naming and imports
• Test files with project test setup patterns
• Config/index files if the convention requires them
• Placeholder implementations that typecheck

4. Verify

# Must pass before considering scaffold complete
npm run lint        # or project equivalent
npm run typecheck   # or tsc --noEmit
npm test -- --bail  # quick check that new tests run

If verification fails, fix issues before delivering. A scaffold that does not pass CI is worse than no scaffold.

Quick Reference

Convention	Where to detect	What to match
File naming	Sibling modules	Case style, suffixes (.service, .controller)
Exports	Barrel/index files	Named vs default, re-export patterns
Dependencies	package.json, imports	DI patterns, constructor args
Tests	Existing test files	Framework, setup, mocking approach
Docs	Existing modules	JSDoc, README, inline comments

Common Scaffolds

See references/common-scaffolds.md for templates covering frequent patterns:

• REST API endpoint module
• React/UI component with tests
• CLI command module
• Database model/migration
• Background job/worker

These are starting points — always adapt to the detected codebase conventions.

Integration

• arsyn:planning — plans may specify modules to scaffold
• arsyn:executing — scaffold tasks within plan execution
• arsyn:tdd — scaffold test files first, then implementation
• arsyn:precision — verify scaffold output matches conventions exactly

Gotchas

• Generic templates over project conventions — Never use a generic "React component" template if the project has established patterns. Always detect first.
• Skipping verification — A scaffold that fails lint or typecheck creates work, not savings. Verify before delivering.
• Over-scaffolding — Generate the minimum viable structure. Extra files that will sit empty are noise.
• Stale reference modules — The most recent module may use newer patterns than older ones. Check multiple examples if conventions evolved.
• Missing barrel exports — If the project uses index.ts barrel files, forgetting to add the new module breaks imports elsewhere.
• Hardcoded paths — Use path aliases or relative imports matching the project convention. Never hardcode absolute filesystem paths.