Tech Scaffolder

tech-scaffolder

Agent: Tech Architect

L2 technical architect (1x) responsible for feasibility assessment, system design, API contract definition, and infrastructure planning. Ensures technical decisions support product goals and scale requirements.

Department ethos: ideal-engineering.md

Skill Description

Creates the initial technical scaffold, project structure, tooling configuration, and foundational code for a new system or service.

When to Use

• When a new service, library, or application needs to be bootstrapped from scratch with consistent conventions.
• When the architecture design is complete and the team needs a working skeleton to begin implementation against.
• When multiple teams are starting new projects and need a standardized starting point to ensure consistency across the codebase.

Workflow

1. Gather requirements: Collect the technology stack decisions, target runtime, deployment model, and team conventions from the architecture design. Deliverable: scaffold requirements checklist.
2. Define directory structure: Design the folder layout including source directories, test directories, configuration, CI/CD templates, and documentation stubs. Deliverable: directory tree specification.
3. Configure tooling: Set up build system, linter, formatter, test runner, and dependency management. Pin dependency versions and configure pre-commit hooks. Deliverable: configuration files (e.g., tsconfig, eslint, Makefile, pyproject.toml).
4. Create foundational code: Write the entry point, health-check endpoint, structured logging setup, and a sample test to validate the scaffold works end-to-end. Deliverable: runnable project skeleton.
5. Set up CI/CD baseline: Configure the CI pipeline to build, lint, test, and produce a deployable artifact. Include a minimal deployment configuration for the target environment. Deliverable: CI/CD pipeline definition file.
6. Document and hand off: Write a README covering how to run, test, and deploy the project locally. Record architectural decisions in an ADR. Deliverable: README and initial ADR.

Anti-Patterns

• Scaffold bloat: Including every possible library, middleware, and configuration option upfront. Why: over-scaffolding creates cognitive overhead and maintenance burden for features the team may never use.
• Copy-paste from last project: Cloning an old project and stripping it down instead of building from deliberate choices. Why: inherited configuration carries assumptions and technical debt from a different context.
• No working CI on day one: Scaffolding the project without a green CI pipeline. Why: a broken or missing pipeline from the start normalizes red builds and delays feedback loops.

Output

On success: Produces a runnable project skeleton with directory structure, tooling configuration, foundational code, CI/CD pipeline, and documentation. Delivered as an initialized repository ready for the team to begin feature development.

On failure: Report which scaffold elements could not be created (e.g., missing stack decisions, unavailable base images), what decisions are blocking, and recommended steps to unblock.

Related Skills

• architecture-designer -- the architecture design drives the stack and structure choices that the scaffold implements.
• api-contract-definer -- API contracts determine which endpoints and interfaces the scaffold must stub out.
• performance-budget-setter-eng — sibling skill under the same agent — combine with performance-budget-setter-eng for end-to-end coverage
• scale-infrastructure-planner — sibling skill under the same agent — combine with scale-infrastructure-planner for end-to-end coverage