Scaffold Project

Scaffold Project Files From macstack.json

Turn a validated macstack.json into a working Claude project. The knowledge-source order below is MANDATORY — it prevents reinventing what the ecosystem already standardized. Each source overrides generic defaults; later sources fill what earlier ones did not.

THE ORDER (never violate)

1. PROTOTYPE FIRST — macstack.json.prototype

If prototype is set, resolve and study it BEFORE writing any file:

• github:owner/repo[#ref] or an https URL → shallow clone: git clone --depth 1 https://github.com/owner/repo "$TMP/proto"
• An absolute path (/Users/...) → a local folder, read it directly.
• Folder/repo → the root macstack.json; merge-by-id yields the inherited content.

From the prototype take (copy, then adapt): directory layout, docker-compose.yml, config files (trigger.config.ts, next.config.ts…), scripts/, .claude/ (rules/commands/skills), .env.example, the CLAUDE.md skeleton, .gitignore. The prototype is the ground truth for HOW this stack is assembled — its files beat any generic template. Prototype chains resolve recursively (the child wins).

2. STACK PLUGINS SECOND — context.plugins.stack[]

Plugins with the stack prefix describe the ARCHITECTURE of the bundle: layers, integration patterns (a-to-b data flows), decision frameworks, .mcp.json with ${VAR}, templates/.env.example, templates/CLAUDE.md.template.

• Install/enable them in .claude/settings.json → enabledPlugins ("<plugin>@<marketplace>": true).
• Generate the project's .mcp.json from the stack plugin's template (or from connections.mcp in macstack.json when no stack plugin exists) — ${VAR} placeholders, NEVER values.
• Architecture rules from the stack plugin's CLAUDE.md.template merge into the project CLAUDE.md.

3. DEV PLUGINS THIRD — context.plugins.technology[]

{tool}-dev plugins define HOW to build with each software in the architecture (SDK patterns, API usage, gotchas). Enable them, and follow their conventions when writing the initial code stubs (e.g.: Directus SDK cache: 'no-store'; Trigger.dev v4 imports from @trigger.dev/sdk/v3). Do not copy their content into the project — plugins own tool knowledge; the project only references them.

4. Only then — generate project files

Backed by sources 1→3, create:

Rules

• "$schema" first: ensure macstack.json starts with "$schema": "https://raw.githubusercontent.com/macstacks/macstack/main/schema/macstack.schema.json" so editors validate live.
• Idempotency: a re-run only adds what is missing and NEVER overwrites user code (existing file with differences → show a diff and ask).
• macstack/ is never overwritten by a prototype: a prototype may seed macstack/README.md and nothing else — a parent's cases and open questions belong to the parent project, not this one.
• No secrets in files: key names only; values arrive via infisical-env.
• Every generated piece must trace to macstack.json (a software/workflow/entity id) — a file bound to nothing is "coding for coding's sake"; do not create it.
• After scaffolding run lint again and report: files created, what came from the prototype / stack plugin / dev plugins, what remains manual (open_questions).