scaffolding

Files (2)

• SKILL.md
• common-scaffolds.md · references/

SKILL.md (first lines)

# 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:

```bash
# 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.

```bash
# 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

```bash
# 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.

From renathoaz/arsyn, MIT.

More from renathoaz/arsyn