scaffold-project

scaffold-project

This skill gives a codebase — new or existing — one deterministic shape, regardless of the implementation language, and writes the conventions into CLAUDE.md so they outlive the session that created them. The goal is that a reader cannot tell which of your repos were scaffolded and which were conformed later.

Six tracks share the same workflow:

• Backend track — services with an entry point (HTTP routes, CLI commands, queue consumers, cron jobs). Reproduces the properties popularized by NestJS/Spring: clear feature boundaries, a thin boundary layer, business logic isolated in injectable services, data access hidden behind repository abstractions, validated DTOs at the edge, centralized error handling, all wired with dependency injection. Canonical reference: references/architecture.md.
• Frontend track — SPA/SSR web apps. Feature-based folders, a typed API layer validated at the boundary, clear state ownership, centralized error handling. Canonical reference: references/frontend-architecture.md.
• TUI track — interactive terminal apps (Textual, Ink, Bubble Tea, Ratatui). The backend layers with a screen as the boundary, plus the terminal's own hard rules: never block the render loop, framework-free services, a declared keymap, guaranteed terminal restore. Canonical reference: references/tui-architecture.md.
• Library / SDK track — no entry point, consumed by other code. One public surface, dependencies passed in, nothing read from the environment. Reference: references/extra-tracks.md.
• Data pipeline / Airflow task track — batch jobs and DAG tasks. Pure transform steps, idempotent writes, a window passed in rather than now(). Reference: references/extra-tracks.md.
• MCP server track — tool servers an agent calls. Thin tool handlers over services, schemas written for a model to read, stdout reserved for protocol frames. Reference: references/extra-tracks.md.

Two things are fixed for every track: the quality caps (assets/claude-md-section-quality.md) and the platform contract (references/platform-contract.md — error shape, pagination, health, logging, config, secrets). Those are what make two repos actually identical rather than merely similarly layered.

The skill produces four things:

1. A skeleton + one fully-worked reference feature in the target language/framework, so there's a concrete pattern to copy for every future feature.
2. Three managed CLAUDE.md sections — track architecture, quality caps, platform contract — so the conventions guide all later code.
3. Mechanical enforcement: the quality caps and the dependency-direction rules configured in the repo's linter and pre-commit hooks, because prose the model may forget is not enforcement.
4. A conforming repo, not just a skeleton: hygiene files, .env.example, dev-run commands, and the handoffs to setup-effect / setup-pre-commit / bd init / vici-cicd-onboard. See references/repo-bootstrap.md.

scripts/check-shape.py answers "which of my repos have drifted?" — run it on a repo or --all ~/Projects; it prints each gap with the fix and exits non-zero when anything drifted.