# Spec 001: Execution Plan

## Sequence

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

---

## Pre-Implementation: Architect Review

**Agent:** architect
**Prompt (COPY VERBATIM):**

> Review the Pydantic models and public API surface proposed in specs/001-scaffold-engine/plan.md (Wave 1).
> Verify: models are clean (no circular deps), library-first principle is maintained, questionnaire data structure is V2-ready (renderable as both CLI prompts and web forms), all module responsibilities are clear.
> Read the whiteboard.md for context on decisions and architecture.
> Report: approved/needs-changes with specific feedback.

---

## Wave 1: Core Library Foundation

**Agent:** python-dev
**Prompt (COPY VERBATIM):**

> Implement Wave 1 of Spec 001: Core Library Foundation.
> Contract: specs/001-scaffold-engine/contract.md (Wave 1 section).
> Plan: specs/001-scaffold-engine/plan.md (Wave 1 section).
>
> Create: pyproject.toml, src/exokit/__init__.py, src/exokit/core/__init__.py, src/exokit/core/models.py, src/exokit/core/questionnaire.py, src/exokit/core/prereqs.py, tests/conftest.py, tests/test_models.py, tests/test_questionnaire.py, tests/test_prereqs.py.
>
> Run quality gates after implementation. Update docs/PROGRESS.md when done.

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

---

## Wave 2: Template Engine + Governance Templates

**Agents:** python-dev (scaffold.py) + template-dev (all .j2 templates) — **PARALLEL**

**Agent: python-dev — Prompt (COPY VERBATIM):**

> Implement the scaffold engine for Wave 2 of Spec 001.
> Contract: specs/001-scaffold-engine/contract.md (Wave 2 section).
> Plan: specs/001-scaffold-engine/plan.md (Wave 2 section).
>
> Create: src/exokit/core/scaffold.py (Jinja2 rendering engine with generate() function).
> Create: tests/test_scaffold.py (rendering engine tests).
>
> The template files will be created by the template-dev agent in parallel. Your scaffold.py should expect templates at src/exokit/core/templates/ with .j2 extension.
> Use the models from core/models.py (created in Wave 1) for the context.
>
> Run quality gates after implementation. Update docs/PROGRESS.md when done.

**Agent: template-dev — Prompt (COPY VERBATIM):**

> Create all Jinja2 templates for Wave 2 of Spec 001.
> Contract: specs/001-scaffold-engine/contract.md (Wave 2 section).
> Plan: specs/001-scaffold-engine/plan.md (Wave 2 section).
>
> Create all .j2 template files listed in the plan under src/exokit/core/templates/.
> The most critical template is CLAUDE.md.j2 — it must be ~400 lines and give Claude everything it needs to build a demo.
>
> Reference these for patterns:
> - Speckit CLAUDE.md: /Users/fouad.alsayadi/Documents/code/speckit/CLAUDE.md (governance patterns)
> - the_demo: /Users/fouad.alsayadi/Documents/demos/the_demo (lakehouse patterns, DLT SQL)
> - template: /Users/fouad.alsayadi/Documents/demos/template (skill references, /demo command)
>
> Create: tests/test_templates/ with rendering tests for each template.
> Each template must have a context comment block at the top documenting required variables.
>
> Run quality gates after implementation. Update docs/PROGRESS.md when done.

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

---

## Wave 3: APX Integration + Skill Bundling

**Agent:** python-dev
**Prompt (COPY VERBATIM):**

> Implement Wave 3 of Spec 001: APX Integration + Skill Bundling.
> Contract: specs/001-scaffold-engine/contract.md (Wave 3 section).
> Plan: specs/001-scaffold-engine/plan.md (Wave 3 section).
>
> Create: src/exokit/core/apx_bridge.py, src/exokit/core/skills.py.
> Create: tests/test_apx_bridge.py, tests/test_skills.py.
>
> For APX: call `apx init` via subprocess with flags --name, --addons ui,lakebase,sql,claude, --profile. Mock in tests.
> For skills: copy from skills/ directory into generated project .claude/skills/. Essential skills list is in the plan.
> For MCP: generate .mcp.json pointing to ai-dev-kit installation.
>
> Run quality gates after implementation. Update docs/PROGRESS.md when done.

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

---

## Wave 4: CLI + End-to-End Integration

**Agent:** python-dev
**Prompt (COPY VERBATIM):**

> Implement Wave 4 of Spec 001: CLI + End-to-End Integration.
> Contract: specs/001-scaffold-engine/contract.md (Wave 4 section).
> Plan: specs/001-scaffold-engine/plan.md (Wave 4 section).
>
> Create: src/exokit/cli.py (Typer CLI with init, validate, update-skills commands).
> Update: src/exokit/core/scaffold.py to orchestrate the full flow (templates + APX + skills + MCP + manifest).
> Create: tests/test_cli.py, tests/test_integration.py.
>
> The CLI must be thin — collect answers via Rich prompts, call core functions, display results.
> Integration test must verify end-to-end scaffold produces a valid project (with mocked APX).
>
> Run quality gates after implementation. Update docs/PROGRESS.md when done.

**Post-wave:** Spawn reviewer agent with wave 4 contract.

---

## Post-Implementation: Final Architecture Review

**Agent:** architect
**Prompt (COPY VERBATIM):**

> Final architecture review for Spec 001.
> Review all modules in src/exokit/ for:
> - Library-first principle (core/ has no Typer/Rich imports)
> - No import cycles
> - Clean Pydantic model hierarchy
> - Template rendering is pure (no filesystem side effects beyond writing output)
> - Public API surface is minimal and intentional
>
> Report: final grade and any issues to address.

---

## Contingency Rules

1. **If any agent fails quality gates:** Max 2 fix attempts. If still failing, escalate to user.
2. **If templates produce invalid output:** Fix the template, not the rendering engine. Templates are the content, engine is the machinery.
3. **If APX subprocess fails:** Check APX is installed (`which apx`). If not available, skip app scaffolding and warn the user.
4. **Never retry silently.** Report all failures to the orchestrator immediately.
