# Spec 001: Contract

## Wave 1 Acceptance Criteria

### Deliverables
- [ ] `pyproject.toml` with all dependencies, tool config, and entry point
- [ ] `src/exokit/__init__.py` with version
- [ ] `src/exokit/core/__init__.py`
- [ ] `src/exokit/core/models.py` — All Pydantic models (Question, QuestionnaireAnswers, DemoManifest, etc.)
- [ ] `src/exokit/core/questionnaire.py` — Question definitions as data + validation
- [ ] `src/exokit/core/prereqs.py` — Prerequisite checks
- [ ] `tests/conftest.py` — Shared fixtures
- [ ] `tests/test_models.py` — Model validation tests
- [ ] `tests/test_questionnaire.py` — Question and defaults tests
- [ ] `tests/test_prereqs.py` — Prereq checks with mocked subprocess

### Quality Gate
```bash
uv run ruff check src/ tests/
uv run ruff format --check src/ tests/
uv run mypy src/exokit/
uv run pytest tests/ -v --cov=src/exokit --cov-report=term-missing
# Coverage >= 80% for wave 1 modules
```

### Success Criteria
- All Pydantic models serialize to/from JSON correctly
- `QuestionnaireAnswers` computes derived fields (bundle_name, app_name)
- Prereq checks return correct results when tools are/aren't installed
- All quality gate commands exit 0

---

## Wave 2 Acceptance Criteria

### Deliverables
- [ ] `src/exokit/core/scaffold.py` — Template rendering engine
- [ ] All templates in `src/exokit/core/templates/` (~25 .j2 files)
- [ ] Dashboard utilities copied (validate_queries.py, inspect_schemas.py, deploy_dashboard_cli.py)
- [ ] `tests/test_scaffold.py` — Scaffold engine tests
- [ ] `tests/test_templates/` — Template rendering validation tests

### Quality Gate
```bash
uv run ruff check src/ tests/
uv run ruff format --check src/ tests/
uv run mypy src/exokit/
uv run pytest tests/ -v --cov=src/exokit --cov-report=term-missing
# Coverage >= 80% for scaffold module
# All templates render without Jinja2 errors
# Rendered YAML/JSON parses correctly
```

### Success Criteria
- `scaffold.generate(sample_answers, tmp_dir)` creates a project directory
- Generated CLAUDE.md is > 300 lines and contains: tech stack, architecture, wave structure, agent roles
- Generated databricks.yml is valid YAML with correct variable substitution
- Generated demo_manifest.json matches DemoManifest Pydantic model
- All lakehouse stub directories exist (data_generation/, pipelines/bronze/silver/gold/, ml/, dashboards/, agents/)
- Dashboard utilities are present and unmodified

---

## Wave 3 Acceptance Criteria

### Deliverables
- [ ] `src/exokit/core/apx_bridge.py` — APX subprocess integration
- [ ] `src/exokit/core/skills.py` — Skill bundler + updater
- [ ] Governance overlay logic for app (3-layer restructure, app CLAUDE.md)
- [ ] `tests/test_apx_bridge.py` — APX integration tests (mocked subprocess)
- [ ] `tests/test_skills.py` — Skill bundling tests

### Quality Gate
```bash
uv run ruff check src/ tests/
uv run ruff format --check src/ tests/
uv run mypy src/exokit/
uv run pytest tests/ -v --cov=src/exokit --cov-report=term-missing
# Coverage >= 80% for apx_bridge and skills modules
```

### Success Criteria
- `apx_bridge.scaffold_app()` calls `apx init` with correct flags (verified via mock)
- After APX scaffold + overlay: app directory has api/, services/, repositories/ structure
- `skills.bundle_skills()` copies all essential skills to target .claude/skills/
- No duplicate skills in bundle
- `.mcp.json` generated with correct ai-dev-kit path

---

## Wave 4 Acceptance Criteria

### Deliverables
- [ ] `src/exokit/cli.py` — Typer CLI with init, validate, update-skills commands
- [ ] End-to-end integration in `scaffold.generate()` orchestrating all modules
- [ ] `tests/test_cli.py` — CLI command tests
- [ ] `tests/test_integration.py` — Full end-to-end scaffold test

### Quality Gate
```bash
uv run ruff check src/ tests/
uv run ruff format --check src/ tests/
uv run mypy src/exokit/
uv run pytest tests/ -v --cov=src/exokit --cov-report=term-missing
# Coverage >= 80% overall
# CLI commands run without errors: exokit --help, exokit validate
```

### Success Criteria
- `exokit init` (with mocked APX) produces a complete project in a temp directory
- Generated project contains: CLAUDE.md, .claude/agents/ (4 files), .claude/skills/ (10+ dirs), databricks.yml, demo_manifest.json, .env.example, apps/main-app/ (with 3-layer backend), src/data_generation/, src/pipelines/, src/ml/, src/dashboards/, src/agents/, docs/, scripts/
- `exokit validate` reports status of all prerequisites
- `exokit update-skills` refreshes skills from source directory
- A Claude Code session opened in the generated project directory would find a valid CLAUDE.md and understand how to proceed
