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

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.