Skip to content

ADR-005: Generator-Based Repository Scaffolding

Field Value
Date 2026-04-02
Status Accepted
Deciders Project maintainer
Supersedes —
Superseded by —

Context and Problem Statement

New repositories need to be initialised with a standard structure, coding guidelines, CI/CD configuration, and Claude Code integration. The setup must enforce spec- and test-driven development from the first commit.

Two fundamentally different approaches exist: a compiled Go generator that writes files deterministically, or Claude Code skills/prompts that let an LLM generate the content at scaffolding time.

Decision Drivers

  • Reproducibility: two developers scaffolding identical projects must get identical output
  • Correctness: generated files (Makefiles, CI YAMLs, go.mod) must be syntactically exact
  • Offline / CI use: scaffolding must work without LLM access
  • Version freshness: pinned tool and library versions should stay up to date without requiring a generator release
  • Maintenance cost: the solution must remain easy to evolve as guidelines change

Considered Options

  1. Compiled Go generator (deterministic, template-based)
  2. LLM skills/prompts only (flexible, non-deterministic)
  3. Hybrid: Go generator for scaffolding + Claude Code skills for version updates ← chosen

Decision Outcome

Chosen option: Option 3 — Hybrid, because it preserves the determinism and correctness guarantees of the Go generator while adding LLM-powered version freshness through dedicated Claude Code skills (/update-versions, /commit).

Positive Consequences

  • Scaffolded repositories are byte-for-byte reproducible given the same inputs
  • No hallucination risk in generated Makefiles, CI configs, or go.mod files
  • Generator works offline and in hermetic CI environments without LLM access
  • /update-versions skill can query registries at runtime, keeping pinned versions current without requiring a generator release
  • Generated repos inherit /update-versions and /commit skills so teams can maintain their own dependencies independently of the generator

Negative Consequences / Risks

  • Two systems to maintain: the Go generator and the Claude Code skills
  • Updating a guideline still requires editing a template and releasing a new generator version (mitigated by repo update command which re-applies generator-owned files)

Pros and Cons of the Options

Option 1 — Compiled Go generator

  • Pro: Fully deterministic — same input always produces the same output
  • Pro: Works offline and in hermetic CI without LLM access
  • Pro: No hallucination risk; templates are exact and version-controlled
  • Pro: Fast (sub-second execution)
  • Con: Pinned versions go stale; updating requires code change + new release
  • Con: Adding a new file type requires Go code, not just a markdown edit

Option 2 — LLM skills/prompts only

  • Pro: Version lookups at scaffolding time — always gets current stable versions
  • Pro: Low barrier to extend: add instructions to a skill prompt
  • Con: Non-deterministic — two runs produce subtly different output (comment wording, YAML key order, whitespace), which breaks Makefiles and causes noise in diffs
  • Con: Hallucination risk for syntax-sensitive files (go.mod, Makefile, CI YAMLs)
  • Con: Requires LLM access; cannot be used in offline or hermetic CI environments
  • Con: Skill prompts become very large (one few-shot example per template file per language)

Option 3 — Hybrid: Go generator + Claude Code skills

  • Pro: Inherits all correctness and reproducibility benefits of Option 1
  • Pro: /update-versions skill provides the version-freshness benefit of Option 2
  • Pro: Generated repos include the skill, so teams own their dependency lifecycle
  • Con: Two systems to maintain, but their responsibilities are clearly separated
  • Analysis document: plan file lexical-baking-porcupine.md (conversation 2026-04-02)
  • Related skills: .claude/skills/update-versions/, .claude/skills/new-project/, .claude/skills/commit/
  • Template skill registration: internal/templating/general_generator.go, internal/templating/update_generator.go