--- name: aep-scaffold description: >- Creates a new AEP project or repairs an existing project's agentic infrastructure and skills layout. Installing AEP itself is /aep-onboard. --- # Scaffold Set up a project for agentic development — either by scaffolding a new monorepo or by onboarding/converging an existing project. Both paths produce a project with OpenSpec, a workspace setup hook, and the canonical BDD e2e-test skill. The existing-project path is an **idempotent audit → confirm → converge** that also repairs drift on re-run. --- ## Mode Selection Detect whether this is a new or existing project: ```bash # Check for existing project markers ls package.json pyproject.toml Cargo.toml go.mod 2>/dev/null ``` - **New project** — empty or near-empty directory, no project config files → [New Project Flow](#new-project-flow) (Phase 1-8) - **Existing project** — has source code and config files → [Existing Project Flow — audit → confirm → converge](#existing-project-flow--audit--confirm--converge) (Phase 0E-6E) --- ## Default Tooling When generating workspace hooks and e2e-test skills, use these defaults unless the project already uses something different: | Language | Package Manager | Test Runner | Dev Server | | ----------------------- | --------------- | ---------------------- | ------------- | | TypeScript / JavaScript | bun | vitest (via Turborepo) | `bun run dev` | | Python | uv | pytest | `uv run dev` | | Rust | cargo | cargo test | `cargo run` | | Go | go | go test | `go run .` | --- # New Project Flow ## Phase 1: Gather Requirements ### Step 1: Understand the project Ask what the user is building — the answer drives every stack recommendation. For project-type presets, the four `--template` presets (t3/pern/mern/uniwind), the full flag/options/defaults table, and per-option decision guidance, read `references/stack-guide.md` — the canonical stack reference. ### Step 2: Present the default and ask about customization > **Default stack (SaaS/web app):** Hono + TanStack Router + Drizzle + SQLite + Better Auth + tRPC + Turborepo + Biome + Bun > > Want to customize anything, or should I use this stack? If the user says "use defaults" or similar, skip to Phase 2. ### Step 3: Walk through customizations Group decisions naturally rather than dumping all options at once: 1. **Core stack** (frontend + backend + API layer) — defines the architecture 2. **Data layer** (database + ORM + DB hosting) — skip if Convex 3. **Auth & payments** — usually quick decisions 4. **Addons** — suggest based on project type 5. **Runtime & deploy** — usually defaults are fine For the tRPC-vs-oRPC choice, framework tradeoffs, and addon guidance, consult `references/stack-guide.md`. Note the hard constraint: **tRPC is incompatible with nuxt/svelte/solid/astro** — use oRPC for non-React frontends. ### Default: in-place scaffold The expected workflow is: **create a git repo → install this plugin → scaffold in-place**. So `.` is the default. > **Note:** In-place scaffold uses `--directory-conflict merge`, which **overwrites** `README.md`, `.gitignore`, and `package.json`. The repo should be empty/fresh when scaffolding. --- ## Phase 2: Tool Check ```bash for cmd in bun git gh openspec; do printf "%-10s" "$cmd:" which $cmd >/dev/null 2>&1 && echo "OK ($(which $cmd))" || echo "MISSING" done ``` | Tool | Install command | | ---------- | -------------------------------------------- | | `bun` | `curl -fsSL https://bun.sh/install \| bash` | | `git` | `xcode-select --install` (macOS) | | `gh` | `brew install gh` | | `openspec` | `npm install -g @fission-ai/openspec@latest` | --- ## Phase 3: Scaffold Project Build the `create-better-t-stack` command from gathered requirements and run it non-interactively. ### Default command (in-place) ```bash bun create better-t-stack@latest . --yes --directory-conflict merge --no-git \ --frontend \ --backend \ --database \ --orm \ --auth \ --api \ --runtime \ --package-manager \ --addons ``` ### Rules - `.` scaffolds into the current directory; `--directory-conflict merge` merges into it; `--no-git` skips git init (the repo already has `.git`) - Always include `--yes` to skip interactive prompts - Only include flags that differ from "none" - If `--database none`, also omit `--orm` and `--dbSetup` - Deploy flags are separate: `--webDeploy cloudflare` and `--serverDeploy cloudflare` - Show the user the full command before running it, and wait for confirmation before executing Before running, check the flag combination against the **Compatibility constraints** table in `references/stack-guide.md` (tRPC/Clerk need React frontends; `self` needs a meta-framework; Workers needs Hono; Polar needs Better Auth; pick one of turborepo/nx; Convex needs no DB/ORM). --- ## Phase 4: Post-Scaffold Verification 1. **Verify structure, install, and build:** ```bash ls apps/ packages/ bun install turbo build ``` 2. **Ensure workflow directories are gitignored:** ```bash # Add agentic workflow directories to .gitignore if not already present grep -q '.dev-workflow/' .gitignore || printf '\n# Agentic development workflow\n.dev-workflow/\n' >> .gitignore grep -q '.feature-workspaces/' .gitignore || printf '.feature-workspaces/\n' >> .gitignore ``` 3. **Commit the scaffold:** ```bash git add -A && git commit -m "feat: scaffold monorepo via Better-T-Stack" ``` A fresh repo is single-branch mode — AEP auto-detects `main` as the integration branch, so set no override. For the two-branch model, the override key, and how `$BASE` resolves, see `/aep-git-ref` "Integration Branch". --- ## Phase 5: Initialize OpenSpec ### Step 1: Run init ```bash openspec init --tools claude,opencode,pi,codex ``` This creates `openspec/` (`config.yaml` = project config + context; `specs/` = source-of-truth specs; `changes/` = proposals + artifacts) and the `.claude/skills/openspec-*/SKILL.md` Claude Code skills (explore, propose, apply, archive). > The `--tools` flag accepts a comma-separated list. Use `--tools all` to configure every supported tool. ### Step 2: Configure project context Update `openspec/config.yaml` with the project's tech stack. Read `package.json` and `bts.jsonc` to determine the stack: ```yaml schema: spec-driven context: | Tech stack: TypeScript, , , / Monorepo: Turborepo + Auth: API: Conventions: conventional commits, trunk-based development ``` ### Step 3: Set up command aliases Copy this skill's four OpenSpec command aliases from `templates/opsx/` into the project's `.claude/commands/opsx/`: ```bash mkdir -p .claude/commands/opsx # copy explore.md, propose.md, apply.md, archive.md from this skill's templates/opsx/ ``` ### Step 4: Verify setup ```bash # Check OpenSpec is initialized openspec list # Check skills were created for skill in openspec-explore openspec-propose openspec-apply-change openspec-archive-change; do printf "%-35s" "$skill:" [ -f ".claude/skills/$skill/SKILL.md" ] && echo "OK" || echo "MISSING" done # Check commands were created for cmd in explore propose apply archive; do printf "%-15s" "/opsx:$cmd:" [ -f ".claude/commands/opsx/$cmd.md" ] && echo "OK" || echo "MISSING" done ``` --- ## Phase 6: Commit OpenSpec ```bash git add -A && git commit -m "feat: initialize OpenSpec for spec-driven development" ``` --- ## Phase 7: Generate Workspace Setup Hook Create the hook that `/aep-build` Phase 0 calls for project-specific setup: ```bash mkdir -p .claude/hooks ``` Generate `.claude/hooks/workspace-setup.sh` tailored to the stack from Phase 1. It installs deps, scans for free ports, starts the dev server, calls `skills/e2e-test/scripts/seed.sh` if present, and **must write** `.dev-workflow/ports.env` — the contract with `/aep-build`: ``` WEB_PORT= SERVER_PORT= BASE_URL=http://localhost: SERVER_URL=http://localhost: ``` Use the template and the full contract in [`references/workspace-hook.md`](references/workspace-hook.md), filling in project-specific values from the stack chosen in Phase 1. ```bash chmod +x .claude/hooks/workspace-setup.sh ``` --- ## Phase 8: Generate the E2E Test Skill (delegate) Hand off to **`/aep-e2e-skill-scaffolding`** — it generates the project-level testing infrastructure that `/aep-build` Phases 5-8 use, in the **canonical BDD layer-gate three-tier** shape: a journey library (natural-language Given/When/Then/Verify), a separate `tool-selection.md` (browser/device tool resolved per environment), and an idempotent `seed.sh`. It reads the stack chosen in Phase 1 to fill its templates and **owns the canonical cross-tool layout** — the real `skills/e2e-test/` dir plus the `.claude` and `.agents` discovery symlinks (visible to Claude Code, Codex, and Pi). It also decides what the target emits (`none` → `policy.md` + `seed.sh` only; `cli`/web/mobile/desktop → adds `journeys/` + `tool-selection.md`) — those target rules live in `/aep-e2e-skill-scaffolding`. ### Commit Verify the delegate actually produced the skill before committing (a missing path with an explicit `git add ` would abort the commit), then stage everything it created: ```bash test -d skills/e2e-test || { echo "ERROR: /aep-e2e-skill-scaffolding did not produce skills/e2e-test — rerun it"; exit 1; } git add -A # stages skills/e2e-test/, the two discovery symlinks, and the workspace hook git commit -m "feat: add workspace hook and BDD e2e-test skill" ``` --- ## Next Steps For the full project layout after scaffolding completes, see [`references/resulting-structure.md`](references/resulting-structure.md). | Command | What it does | | --------------- | ------------------------------------------------------------------- | | `/aep-dispatch` | Pick the next story and start building (if product context exists) | | `/aep-design` | Start designing a feature directly (standalone, no product context) | | `bun run dev` | Start the dev server | | `openspec list` | List active changes | --- ## Guardrails - **Show the full command and wait for confirmation** before running scaffold; include `--yes` (non-interactive), `--no-git` (in-place), and warn that in-place overwrites README.md, .gitignore, and package.json. - **Commit OpenSpec artifacts to git** — they are part of the project record. - **Never overwrite an existing OpenSpec config** — check `openspec/config.yaml` exists before `openspec init`. - **Hand-authored content is never overwritten** (journeys, specs, prose) — the existing-project flow normalizes layout and upgrades generated infra idempotently, leaving hand-written files intact. - **Version re-pin is recommend-only** — scaffold prints the `npx skills add@` commands; the user runs them in a deliberate own-PR re-pin. --- # Existing Project Flow — audit → confirm → converge For projects that already have source code. This flow is **idempotent**: run it to onboard an existing project **or** re-run it later to repair **drift** toward the current AEP standard (healthy per-agent skills layout, BDD e2e skill, current pin). It reports first, asks, then converges, under the Guardrails rule above. Read [`references/converge-flow.md`](references/converge-flow.md) — the canonical account of this flow: how to read each audit category, the observability→telemetry-candidate handling, and the per-category converge detail. In commands below, replace `` with the absolute directory containing this `SKILL.md`; it is notation, not an environment variable or a target-project-relative path. ## Phase 0E: Status Check (stack + pin) `scripts/audit.sh` opens by detecting language, package manager, monorepo tool, backend/frontend signal, and the AEP pin vs latest release. Interpret those readings per `references/converge-flow.md` → "Reading the audit" (package-manager recommendation, default e2e `target`). --- ## Phase 1E: Audit (drift-aware), grouped by category Run the read-only audit. Nothing is changed in this phase. ```bash bash "/scripts/audit.sh" ``` It prints `[ok]`/`[DRIFT]` per check and **exits non-zero while any `[DRIFT]` remains** (exit 0 when clean). What each category (A–E) means and how observability is handled: `references/converge-flow.md`. --- ## Phase 2E: Report + Confirm Direction Present the audit as a **current → target** summary per category, ask which categories to apply (**default = fix all drift + gaps**), and converge only the confirmed ones in Phase 3E. The summary shape is in `references/converge-flow.md` → "Report + confirm". --- ## Phase 3E: Converge (idempotent) Apply only the confirmed changes; each step is a no-op when already satisfied. Run the mechanical fixes, then the two model-driven steps. Detail for every category is in `references/converge-flow.md`. ```bash bash "/scripts/converge.sh" --category A --category C ``` Pass only confirmed mechanical categories (`A`, `C`, or `E`), repeating `--category`; skip the script if none were confirmed. E only prints a re-pin recommendation; B and D remain model-driven. - **B. E2E-test skill** — delegate to **`/aep-e2e-skill-scaffolding`**; it creates or upgrades the skill idempotently. - **C. Remaining infra** — for each missing item: git repo (`git init -b main && git add -A && git commit -m "chore: initial commit"`); OpenSpec (follow [Phase 5](#phase-5-initialize-openspec)); workspace hook (follow [Phase 7](#phase-7-generate-workspace-setup-hook)). --- ## Phase 4E: Verify Re-run the audit until it **exits 0** — every confirmed category then reads `[ok]`: ```bash bash "/scripts/audit.sh" ``` --- ## Phase 5E: Commit ```bash git add -A git commit -m "feat: converge agentic development infrastructure" ``` --- ## Phase 6E: Next Steps | Command | What it does | | ---------------------------- | --------------------------------------------------------- | | `/aep-design` | Start designing a feature (standalone mode) | | `/aep-dispatch` | Pick the next story (if product context exists) | | `/aep-e2e-skill-scaffolding` | Generate/upgrade the BDD layer-gate e2e-test skill | | `/aep-git-ref` | AEP git + worktree reference (worktree lifecycle, naming) |