# Spec 002: Execution Plan

## Sequence

```
Wave 1 (python-dev + template-dev parallel) → reviewer → gatekeeper →
Wave 2 (template-dev) → reviewer → gatekeeper →
Wave 3 (python-dev) → reviewer → gatekeeper →
Wave 4 (python-dev) → reviewer → gatekeeper →
Final review (architect)
```

---

## Wave 1: Fix Broken Templates

**Agents:** python-dev (scaffold.py, tests) + template-dev (YAML/TOML templates) — **PARALLEL**

**Agent: python-dev — Prompt:**

> Implement Wave 1 of Spec 002: Fix scaffold.py and tests.
> Contract: specs/002-scaffold-feedback/contract.md (Wave 1 section).
> Plan: specs/002-scaffold-feedback/plan.md (Sections 1.7, 1.8, 1.9).
>
> Changes to scaffold.py: Remove `_STATIC_FILES` list and `_copy_static_files_from()` function. Remove `static_files_dir` parameter from `generate()`. Add `INDUSTRY_DISPLAY_NAMES` dict. Fix `display_name` logic. Add 5 new entries to `_STUB_DIRECTORIES` (4 agent-memory dirs + resources/dashboards).
>
> Delete: `src/exokit/core/templates/static/` directory entirely.
>
> Update tests: `test_scaffold.py` (remove static file tests, add display_name + stub dir tests), `test_integration.py` (remove static file test, add agent-memory + dashboards dir tests), `test_template_rendering.py` (add requirements.txt.j2 to TEMPLATE_FILES, update job task count assertions, add pipeline target check, add databricks.yml variable checks).
>
> Run quality gates after implementation.

**Agent: template-dev — Prompt:**

> Implement Wave 1 of Spec 002: Fix broken templates.
> Contract: specs/002-scaffold-feedback/contract.md (Wave 1 section).
> Plan: specs/002-scaffold-feedback/plan.md (Sections 1.1-1.6).
>
> Fix these templates:
> 1. `templates/root/databricks.yml.j2` — add pipeline_target_schema + schema variables
> 2. `templates/lakehouse/resources/jobs/data_generation_job.yml.j2` — replace fake tasks with setup_catalog only
> 3. `templates/lakehouse/resources/jobs/ml_training_job.yml.j2` — comment out tasks, remove ${var.schema}
> 4. `templates/lakehouse/resources/pipelines/main_pipeline.yml.j2` — add target field
> 5. `templates/root/pyproject.toml.j2` — add hatch config + ruff ignores + fix description
> 6. Create `templates/root/requirements.txt.j2` — universal deps
>
> Run quality gates after implementation.

**Post-wave:** Spawn reviewer agent with Wave 1 contract.

---

## Wave 2: New Templates

**Agent:** template-dev

**Prompt:**

> Implement Wave 2 of Spec 002: Create new templates and update existing ones.
> Contract: specs/002-scaffold-feedback/contract.md (Wave 2 section).
> Plan: specs/002-scaffold-feedback/plan.md (Sections 2.1-2.8).
>
> Create 9 new templates:
> 1. `templates/lakehouse/src/data_generation/setup_catalog.py.j2` — Databricks notebook, creates catalog + default schema + volumes
> 2. `templates/lakehouse/src/data_generation/CLAUDE.md.j2` — data gen patterns from FSI feedback Section 4
> 3. `templates/lakehouse/src/pipelines/CLAUDE.md.j2` — DLT patterns from FSI feedback Section 4
> 4. `templates/lakehouse/src/ml/CLAUDE.md.j2` — ML patterns from FSI feedback Section 4
> 5. `templates/scripts/deploy-all.sh.j2` — orchestrator calling lakehouse + app deploy
> 6. `templates/scripts/deploy-lakehouse.sh.j2` — full lifecycle deploy with --skip-to flag
> 7. `templates/scripts/deploy-app.sh.j2` — app build + deploy + SP permissions
> 8. `templates/docs/TALK_TRACK.md.j2` — empty structure stub
>
> Update existing templates:
> 9. `templates/scripts/deploy.sh.j2` — redirect to deploy-lakehouse.sh
> 10. `templates/root/.env.example.j2` — consolidate vars for deploy scripts
> 11. `templates/root/CLAUDE.md.j2` — reference new files/scripts, fix naming
> 12. `templates/docs/LESSONS_LEARNED.md.j2` — pre-populate with ≥5 gotchas
>
> Add all new templates to TEMPLATE_FILES in test_template_rendering.py with appropriate tests.
> Reference content from: /Users/fouad.alsayadi/Documents/industry_demos/fsi-demo/docs/SCAFFOLDING_FEEDBACK.md (Section 4 for directory CLAUDE.md content), /Users/fouad.alsayadi/Documents/industry_demos/fsi-demo/docs/LESSONS_LEARNED.md (for pre-populated gotchas), /Users/fouad.alsayadi/Documents/industry_demos/fsi-demo/apps/main-app/deploy.sh (for deploy-app.sh template).
>
> Run quality gates after implementation.

**Post-wave:** Spawn reviewer agent with Wave 2 contract.

---

## Wave 3: APX Bridge Fixes

**Agent:** python-dev

**Prompt:**

> Implement Wave 3 of Spec 002: Fix APX bridge and related templates.
> Contract: specs/002-scaffold-feedback/contract.md (Wave 3 section).
> Plan: specs/002-scaffold-feedback/plan.md (Sections 3.1-3.10).
>
> APX bridge changes (apx_bridge.py):
> 1. Fix overlay: raise APXScaffoldError if src/{slug}/backend/ doesn't exist (no fallback to app root)
> 2. Add `_postprocess_apx_config()`: remove database_instances, align profile/host/warehouse
> 3. Add `_install_shadcn_components()`: pre-install common shadcn/ui components (graceful failure)
> 4. Add `_postprocess_app_env()`: ensure app .env has warehouse/catalog/profile
> 5. Add `_write_app_readme()`: replace APX's README with setup instructions
> 6. Enhance `_APP_CLAUDE_MD`: add SP vs OBO, SQL warehouse, shadcn, deployment patterns
>
> Template changes:
> 7. `build-next.md.j2` — add Step 0.6: Apply Plan to Placeholders
> 8. `deploy.md.j2` — reference new deploy scripts
> 9. `validate.sh.j2` — add bundle validate + structure checks
> 10. `IMPLEMENTATION_PLAN.md.j2` — mark as "replaced by /build-next"
>
> Update tests: test_apx_bridge.py (strict overlay, config post-processing, app README), test_template_rendering.py (Step 0.6, new script refs).
>
> Note: PyYAML is already a dependency via pydantic-settings. Use yaml.safe_load() + yaml.dump() for YAML post-processing. Make sure _postprocess_apx_config handles missing keys gracefully (APX version may vary).
>
> Run quality gates after implementation.

**Post-wave:** Spawn reviewer agent with Wave 3 contract.

---

## Wave 4: Integration + Validation

**Agent:** python-dev

**Prompt:**

> Implement Wave 4 of Spec 002: Integration tests and documentation.
> Contract: specs/002-scaffold-feedback/contract.md (Wave 4 section).
> Plan: specs/002-scaffold-feedback/plan.md (Sections 4.1-4.4).
>
> Integration tests (test_integration.py):
> 1. `TestBundleValidateReady`: generate scaffold, parse YAML, verify all ${var.X} references have declarations in databricks.yml
> 2. `TestDisplayNameNoDuplication`: generate with company="", industry="fsi", grep all files for "FSI FSI" — expect 0
> 3. `TestDirectoryStructureComplete`: verify all new dirs/files exist (agent-memory, dashboards, requirements.txt, setup_catalog.py, 3 directory CLAUDEs, 3 deploy scripts)
>
> Documentation:
> 4. Update docs/PROGRESS.md with Spec 002 wave status
> 5. Update whiteboard.md with decisions: hello-world exit criteria, deploy script split, INDUSTRY_DISPLAY_NAMES, APX post-processing, static file removal
>
> Run full quality gates. Coverage must be >= 80%.

**Post-wave:** Spawn reviewer agent with Wave 4 contract. Then spawn architect for final review.

---

## Final Review

**Agent:** architect

**Prompt:**

> Review the complete Spec 002 implementation.
> Read: specs/002-scaffold-feedback/contract.md for acceptance criteria.
> Verify: all feedback items from the coverage checklist are addressed, templates are well-structured, APX bridge changes are clean, tests are comprehensive.
> Grade: A (approve) / B (minor fixes) / C (needs rework).
