# Spec 001: Scaffold Engine

## Background

We need the core scaffolding engine that powers `exokit init`. This is the foundation everything else builds on. Given a set of questionnaire answers, the engine must produce a complete, valid demo project directory with all governance, configuration, and skeleton files — ready for Claude to start building.

## User Story

**As a** Databricks SE/partner engineer,
**I want to** run `exokit init`, answer 7-10 questions about my demo,
**and get** a complete project scaffold with CLAUDE.md, agents, skills, databricks.yml, app skeleton, and lakehouse stubs — so I can immediately start a Claude Code session and begin building.

## Scope

### In Scope
- Interactive CLI questionnaire (Typer + Rich)
- Jinja2 template rendering engine
- Pre-flight prerequisite checks (databricks CLI, uv, node, apx, auth)
- Demo manifest builder (demo_manifest.json)
- App scaffolding via APX subprocess call
- Governance overlay (CLAUDE.md, agents, supplements) on top of APX scaffold
- Skill bundling (copy essential skills into generated project)
- MCP server configuration (.mcp.json for ai-dev-kit)
- Configuration file generation (databricks.yml, .env.example, catalog_schema.json)
- Lakehouse directory stubs (src/data_generation/, src/pipelines/, src/ml/, src/dashboards/, src/agents/)

### Out of Scope
- Content generation (Claude fills this later)
- Databricks deployment (separate command)
- V2 web app wrapper
- The FSI demo itself (separate phase)
- Skill authoring (we bundle existing skills)

## Waves

### Wave 1: Core Library Foundation
**User can:** Nothing yet (internal foundation).
**Deliverables:** pyproject.toml, Pydantic models (questionnaire, manifest, config), questionnaire data definitions, prereqs module, basic test infrastructure.

### Wave 2: Template Engine + Governance Templates
**User can:** Nothing yet (templates exist but no CLI to invoke them).
**Deliverables:** Jinja2 rendering engine (scaffold.py), all governance templates (CLAUDE.md.j2, agent .j2 files, supplement .j2 files), config templates (databricks.yml.j2, .env.example.j2, demo_manifest.json.j2), lakehouse stub templates. Template rendering tests.

### Wave 3: APX Integration + Skill Bundling
**User can:** Nothing yet (integration pieces).
**Deliverables:** APX bridge module (subprocess call to `apx init`), governance overlay logic (copy our files on top of APX scaffold), skill bundler (copy skills from skills/ into generated project), MCP configuration generator (.mcp.json).

### Wave 4: CLI + End-to-End Integration
**User can:** Run `exokit init`, answer questions, get a complete scaffold. Run `exokit validate` to check prerequisites.
**Deliverables:** Typer CLI (cli.py), end-to-end integration tying all modules together, `exokit validate` command, `exokit update-skills` command, full integration tests.

## Risk Assessment

| Risk | Likelihood | Mitigation |
|------|-----------|-----------|
| APX subprocess call fails on different platforms | Medium | Mock APX in tests. Manual testing on macOS. Document prerequisites. |
| Template rendering produces invalid YAML/JSON | Medium | Parse rendered output in tests. Validate against schemas. |
| Too many questionnaire questions → user fatigue | Low | Cap at 10. Smart defaults for everything. |
| Skill bundling copies stale versions | Low | Version stamp in manifest. `update-skills` command. |
