aep-scaffold

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:

# 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 (Phase 1-8)

• Existing project — has source code and config files

→ 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:

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

for cmd in bun git gh openspec; do
  printf "%-10s" "$cmd:"
  which $cmd >/dev/null 2>&1 && echo "OK ($(which $cmd))" || echo "MISSING"
done

Phase 3: Scaffold Project

Build the create-better-t-stack command from gathered requirements and run it non-interactively.

Default command (in-place)

bun create better-t-stack@latest . --yes --directory-conflict merge --no-git \
  --frontend <frontend> \
  --backend <backend> \
  --database <database> \
  --orm <orm> \
  --auth <auth> \
  --api <api> \
  --runtime <runtime> \
  --package-manager <pm> \
  --addons <addon1,addon2,...>

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:

   ls apps/ packages/
   bun install
   turbo build

1. Ensure workflow directories are gitignored:

   # 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

1. Commit the scaffold:

   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

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:

schema: spec-driven

context: |
  Tech stack: TypeScript, <frontend>, <backend>, <database>/<orm>
  Monorepo: Turborepo + <package-manager>
  Auth: <auth-provider>
  API: <api-layer>
  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/:

mkdir -p .claude/commands/opsx
# copy explore.md, propose.md, apply.md, archive.md from this skill's templates/opsx/

Step 4: Verify setup

# 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

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:

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=<port>
SERVER_PORT=<port>
BASE_URL=http://localhost:<web-port>
SERVER_URL=http://localhost:<server-port>

Use the template and the full contract in `references/workspace-hook.md`, filling in project-specific values from the stack chosen in Phase 1.

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 <path> would abort the commit), then stage everything it created:

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`.

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@<newtag> 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` — 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 <aep-scaffold-dir> 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 "<aep-scaffold-dir>/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 "<aep-scaffold-dir>/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); workspace hook (follow Phase 7).

Phase 4E: Verify

Re-run the audit until it exits 0 — every confirmed category then reads [ok]:

bash "<aep-scaffold-dir>/scripts/audit.sh"

Phase 5E: Commit

git add -A
git commit -m "feat: converge agentic development infrastructure"

Phase 6E: Next Steps