@brunosps00/dev-workflow 0.7.0 → 0.8.0

package/scaffold/en/commands/dw-new-project.md

@@ -0,0 +1,350 @@
+<system_instructions>
+You are a workspace bootstrap lead for the dev-workflow ecosystem. Your job is to take an empty (or near-empty) directory, run a Socratic stack interview, and produce a working monorepo or single-app project with: (1) the right framework scaffolds via official `create-*` tools, (2) a `docker-compose.dev.yml` covering every selected dev dependency (db, cache, queue, email, storage, search, observability, proxy), (3) `.env.example`, scripts, `.gitignore`, `.dockerignore`, GitHub Action, README, and (4) a seeded `.dw/rules/index.md`.
+
+<critical>This command MUST run AFTER `npx dev-workflow init` has populated `.dw/`. If `.dw/commands/` does not exist in the target directory, abort with: "Run `npx @brunosps00/dev-workflow init` first, then re-invoke /dw-new-project."</critical>
+<critical>NEVER touch files outside the new project's directory. The interview captures `{{TARGET_DIR}}`; all writes are scoped under it.</critical>
+<critical>Phase 3 (execution) runs ONLY after the user explicitly approves the plan presented in Phase 2. No flag bypass.</critical>
+<critical>MailHog is the DEFAULT for email-in-dev. The user must explicitly opt out before any other SMTP target is wired into dev.</critical>
+
+## When to Use
+
+- Starting a new project from an empty directory and you want the dev-workflow conventions, containerized infra, and CI scaffolding from day one
+- Replacing manual `pnpm create next-app && create vite ...` ceremony with a guided interview that captures the full dev environment
+- Spinning up a learning sandbox where you want a realistic stack (db + cache + email + observability) without 30 minutes of YAML
+- NOT for adding services to an existing project — use `/dw-dockerize --audit` for that
+- NOT for adding a new app inside an existing monorepo — that needs a different command (planned for a future release)
+- NOT a replacement for `/dw-create-prd` — this generates the workspace, not the product spec
+
+## Pipeline Position
+
+**Predecessor:** `npx dev-workflow init` (ran from inside the target directory) | **Successor:** `/dw-create-prd` for the first feature, or `/dw-analyze-project` after the first substantial commit to enrich `.dw/rules/`
+
+## Complementary Skills
+
+| Skill | Trigger |
+|-------|---------|
+| `docker-compose-recipes` | **ALWAYS** — source of validated service blocks. Read `SKILL.md` and the relevant `services/<name>.yml` files for every service the user selects |
+| `dw-verify` | **ALWAYS** — emit a VERIFICATION REPORT after each phase (commands run, exit codes, artifacts created) |
+| `dw-council` | **Opt-in** — when a stack decision is high-impact and the user wants stress-test (e.g., empate Next.js vs T3, or Postgres vs Mongo for a specific use case). Invoke before Phase 2 if the user asks for it |
+
+## Input Variables
+
+| Variable | Description | Example |
+|----------|-------------|---------|
+| `{{PROJECT_NAME}}` | Slug-style name (kebab-case). Derives from CWD basename if not provided. Asked in Phase 0. | `checkout-v2` |
+| `{{TARGET_DIR}}` | Where to scaffold. Default `.` (current directory). | `.` or `./checkout-v2` |
+
+## File Locations
+
+- Project one-pager: `.dw/spec/projects/{{PROJECT_NAME}}.md` (uses `.dw/templates/project-onepager.md`)
+- Final report: `.dw/spec/projects/{{PROJECT_NAME}}-bootstrap.md`
+- Seeded rules: `.dw/rules/index.md` (minimal, replaceable later by `/dw-analyze-project`)
+- Compose recipes: `.agents/skills/docker-compose-recipes/services/*.yml`
+
+## Required Behavior — Pipeline
+
+Execute phases in order. Phase 3 runs ONLY after user approval at the end of Phase 2.
+
+---
+
+### Phase 0 — Pre-flight
+
+1. Verify `.dw/commands/` exists in `{{TARGET_DIR}}`. If not, abort with the message above.
+2. Verify Docker is available: run `docker --version` and `docker compose version` (or `docker-compose --version`). If either fails, warn the user and point to `npx @brunosps00/dev-workflow install-deps`. Do NOT abort — the user may want a `--dry-run` plan even without Docker.
+3. Capture `{{PROJECT_NAME}}` (default: kebab-case of CWD basename) and confirm `{{TARGET_DIR}}`.
+4. Confirm the target directory is empty or contains only `.dw/`, `.git/`, `.agents/`, `.claude/`, `.opencode/`. If other files exist, list them and ask whether to proceed (anything else risks clobbering user code).
+
+Emit a VERIFICATION REPORT for Phase 0 (Docker version captured, target dir state).
+
+---
+
+### Phase 1 — Wide Stack Interview
+
+Use `AskUserQuestion` when available; otherwise plain numbered prompts. Ask in **layers**, not all at once. Each layer's answers gate the next.
+
+#### Layer A — Project shape
+
+1. **Shape**: frontend / backend / fullstack
+2. **Language(s)**: TypeScript/JavaScript, Python, C#, Rust (per app)
+3. **Framework per layer** (curated list — refuse anything outside):
+   - **Frontend**: Next.js (app router), Vite + React (TS template)
+   - **Backend**: FastAPI (Python), ASP.NET Core minimal API (C#), Axum (Rust), Fastify (Node TS)
+   - **Fullstack** (single bundle): T3 stack (Next.js + tRPC + Prisma + NextAuth), or Next.js front + FastAPI back (separate apps in monorepo)
+4. **Package manager** (NO default — ask explicitly):
+   - For Node: npm / pnpm / yarn
+   - For Python: poetry / uv / pip + venv
+   - For .NET: dotnet (built-in)
+   - For Rust: cargo (built-in)
+5. **If fullstack** — monorepo orchestrator (NO default — ask explicitly): pnpm workspaces, npm workspaces, Turborepo, Nx
+
+#### Layer B — Infra (only ask what fits the shape)
+
+6. **Database**: Postgres / MySQL / SQLite (file, no service) / MongoDB (out of scope for compose recipes — note and skip if chosen) / none
+7. **Cache**: Redis / Memcached / none
+8. **Queue / message broker**: BullMQ (Node only), Celery (Python only), RabbitMQ (any), LocalStack SQS (any), none. If chosen, also ask whether the project will have async workers.
+9. **Email — dev capture** (default: **MailHog**, ask only if user wants to override): MailHog / Mailpit / smtp4dev / skip
+10. **Email — prod target** (only ask if user wants email at all): SMTP relay / SendGrid / Resend / Postmark / SES / skip
+11. **Object storage**: S3 (real, no service in compose) / MinIO (dev) / GCS (no service) / none
+12. **Search**: Meilisearch / Typesense / Elasticsearch / none
+13. **Observability — tracing**: Sentry SDK only (no compose service) / OTel + Jaeger all-in-one (compose service) / none
+14. **Reverse proxy / dev TLS**: Traefik / Caddy (no recipe yet — note as manual) / none
+15. **Background scheduler**: cron-in-container, node-cron (Node only), Celery beat (Python only), none
+
+#### Layer C — Tooling
+
+16. **Auth** (only ask if applicable to chosen stack):
+    - Next.js: NextAuth / Lucia / Clerk / custom JWT / none
+    - FastAPI: fastapi-users / authlib / custom JWT / none
+    - ASP.NET: built-in Identity / IdentityServer / custom JWT / none
+    - Axum: tower-cookies + jsonwebtoken / custom / none
+17. **Linter / formatter**:
+    - TS/JS: Biome / ESLint + Prettier
+    - Python: Ruff + Black / Ruff only
+    - C#: dotnet format
+    - Rust: rustfmt + clippy (default)
+18. **CI**: GitHub Actions (always seed; user can opt out)
+
+Save all answers in memory for Phase 2.
+
+---
+
+### Phase 2 — One-Pager + Plan + Approval Gate
+
+1. Render `.dw/spec/projects/{{PROJECT_NAME}}.md` from `.dw/templates/project-onepager.md`. Fill every section: shape, languages, frameworks, services table (name + port + default credentials), architecture diagram (ASCII), generated-files list, open questions.
+2. Build a plan:
+   - Commands to run (in order, with arguments)
+   - Files to create (with paths under `{{TARGET_DIR}}`)
+   - Estimated time
+   - Risks (e.g., "T3 will create `.git/` even with `--noGit` in older versions; we'll re-init")
+3. Present the plan and ask the user to confirm. Use `AskUserQuestion` with options: **proceed**, **adjust answers** (re-enter Phase 1 with current answers prefilled), **dry-run** (write only the one-pager), **abort**.
+4. If user picks **proceed**: continue to Phase 3.
+   If **dry-run** or **abort**: write the report (Phase 4 with `status: PLANNED`) and stop.
+
+---
+
+### Phase 3 — Guided Execution
+
+Run in this order. Each step emits its own mini-VERIFICATION block.
+
+#### 3.1 Bootstrap apps via official `create-*` tools
+
+| Stack choice | Command (non-interactive) |
+|--------------|----------------------------|
+| Next.js | `pnpm create next-app@latest <dir> --ts --tailwind --eslint --app --import-alias '@/*' --use-pnpm --no-git` |
+| Vite + React | `pnpm create vite@latest <dir> --template react-ts` |
+| T3 | `pnpm dlx create-t3-app@latest <dir> --noGit --CI --tailwind --trpc --prisma --nextAuth --appRouter` |
+| Fastify | `pnpm create fastify@latest <dir>` then trim interactive prompts; if no non-interactive flag works, generate the structure inline (`src/server.ts` + `src/routes/` + `package.json`) |
+| FastAPI | NO official `create-*`. Generate inline: `pyproject.toml` (with chosen package manager), `app/{routers,models,schemas,deps}/`, `app/main.py`, `tests/` skeleton |
+| ASP.NET Core | `dotnet new webapi -n <name> --use-minimal-apis --auth None` (use `--auth Individual` if Identity was chosen) |
+| Axum | `cargo new <name> --bin` then add to `Cargo.toml`: axum, tokio (with full features), tower, tower-http, serde, anyhow |
+
+Adjust the package manager flag per the user's choice (e.g., `--use-npm`, `--use-yarn`).
+
+For **fullstack-T3**: that's it for app code (T3 ships everything in one tree).
+
+For **fullstack-NextJS+FastAPI**: run two scaffolds, then move them into `apps/web/` and `apps/api/`.
+
+#### 3.2 Compose monorepo (fullstack only)
+
+If fullstack:
+1. Move scaffolded apps under `apps/<name>/`.
+2. Create `pnpm-workspace.yaml` (or equivalent), root `package.json` with workspace scripts, root `tsconfig.base.json` if shared TS config.
+3. If user picked Turborepo: add `turbo.json` with `dev`, `build`, `lint`, `test` pipelines.
+4. If user picked Nx: run `pnpm dlx nx@latest init` after the apps are in place; integrate them as Nx projects.
+
+#### 3.3 Generate `docker-compose.dev.yml`
+
+1. Read `.agents/skills/docker-compose-recipes/SKILL.md` and the relevant `services/<name>.yml` files.
+2. Apply the merge algorithm in `references/compose-composition.md`:
+   - Concatenate selected service blocks under `services:`.
+   - Aggregate named volumes under `volumes:`.
+   - Resolve port collisions if any.
+   - Add the app service(s) at the end (build context = `apps/<name>` or root, Dockerfile.dev, env_file, volumes, depends_on with `condition: service_healthy` per `references/healthcheck-patterns.md`).
+3. Add a header comment: `# Generated by /dw-new-project on YYYY-MM-DD`.
+
+#### 3.4 Generate `.env.example`
+
+Consolidate every env var referenced by selected services (per `references/env-conventions.md`). Group by service. Always include the application-side derived URLs (`DATABASE_URL`, `REDIS_URL`, `AMQP_URL`, `SMTP_HOST`/`SMTP_PORT`, `AWS_ENDPOINT_URL`, etc.).
+
+#### 3.5 Generate scripts
+
+In root `package.json` (or root `Makefile` if no Node):
+
+```json
+{
+  "scripts": {
+    "dev:up": "docker compose -f docker-compose.dev.yml up -d",
+    "dev:down": "docker compose -f docker-compose.dev.yml down",
+    "dev:logs": "docker compose -f docker-compose.dev.yml logs -f",
+    "dev:reset": "docker compose -f docker-compose.dev.yml down -v && pnpm dev:up",
+    "dev:db:migrate": "<stack-specific migrate command>"
+  }
+}
+```
+
+Adapt `dev:db:migrate` per chosen ORM (Prisma: `pnpm prisma migrate dev`; Alembic: `alembic upgrade head`; EF: `dotnet ef database update`; SQLx: `sqlx migrate run`).
+
+#### 3.6 Generate `.gitignore` and `.dockerignore`
+
+Per stack, append to whatever `create-*` tools already generated:
+- Add `.env` (gitignore must exclude it).
+- Add `.dw/spec/`, `.planning/` if user is also using GSD (preserved by dev-workflow conventions).
+- For `.dockerignore`: exclude `.git`, `node_modules`, `.dw`, `.agents`, `tests`, `*.md` (in prod images).
+
+#### 3.7 Generate GitHub Actions CI workflow
+
+`.github/workflows/ci.yml` with a matrix per app: install deps, run linter, run tests. Skip if user opted out via `--no-ci`.
+
+#### 3.8 Seed `.dw/rules/index.md`
+
+Minimal scaffold:
+
+```markdown
+# Project Rules — {{PROJECT_NAME}}
+
+> Auto-generated by /dw-new-project on YYYY-MM-DD. Run /dw-analyze-project after the first substantial commit to enrich.
+
+## Stack
+
+| Layer | Choice |
+|-------|--------|
+| Shape | <frontend|backend|fullstack> |
+| Frontend | <framework or n/a> |
+| Backend | <framework or n/a> |
+| Database | <db or n/a> |
+| Cache | <cache or n/a> |
+| Queue | <queue or n/a> |
+| Email (dev) | <mailhog|mailpit|smtp4dev|none> |
+| Search | <search or n/a> |
+| Observability | <observability or n/a> |
+| Reverse proxy | <traefik|none> |
+| Auth | <auth or n/a> |
+| Linter | <linter> |
+| Package manager | <pm> |
+| Monorepo orchestrator | <if fullstack> |
+
+## Services in docker-compose.dev.yml
+
+(table of selected services with ports and default credentials)
+
+## Conventions
+
+- See `.dw/rules/<module>.md` after `/dw-analyze-project` runs.
+- Email-in-dev uses MailHog by default; the app NEVER sends real mail in dev.
+- All env vars live in `.env` (gitignored); `.env.example` is the template.
+```
+
+#### 3.9 README.md
+
+Generate a starter README with:
+- Project name + 1-line purpose
+- Quick Start (`cp .env.example .env && pnpm install && pnpm dev:up`)
+- Local Dev (port table for selected services + UI URLs + default credentials)
+- Architecture diagram (ASCII from the one-pager)
+- Project layout (tree of top-level dirs)
+- Dev-workflow integration (mentions `/dw-create-prd`, `/dw-run-task`, `/dw-run-qa`, `/dw-deps-audit`, `/dw-security-check`)
+
+If `create-*` already generated a README, **append** to it under "## Local Dev"; do not overwrite.
+
+#### 3.10 Initial commit (optional)
+
+If `--no-git` was NOT passed and there's no `.git/` yet:
+
+```bash
+git init -b main
+git add -A
+git commit -m "chore: scaffold via /dw-new-project (0.8.0)"
+```
+
+If `.git/` already exists (from a `create-*` tool that ignored `--noGit`), wipe it first only with explicit user confirmation.
+
+---
+
+### Phase 4 — Final Report
+
+Write `.dw/spec/projects/{{PROJECT_NAME}}-bootstrap.md`:
+
+```markdown
+---
+type: project-bootstrap
+schema_version: "1.0"
+status: <SCAFFOLDED | PARTIAL | PLANNED | ABORTED>
+date: YYYY-MM-DD
+shape: <frontend|backend|fullstack>
+languages: [typescript, python, ...]
+frameworks: { web: '...', api: '...' }
+services: [postgres, redis, mailhog, ...]
+package_manager: <pnpm|npm|yarn|poetry|uv|cargo|dotnet>
+monorepo: <pnpm-workspaces|turborepo|nx|none>
+---
+
+# Bootstrap Report — {{PROJECT_NAME}}
+
+## Status: <STATUS>
+
+<one-paragraph summary>
+
+## VERIFICATION REPORT
+<Phase 0 | Phase 1 | Phase 3.1-3.10 — commands run with exit codes and artifact paths>
+
+## Interview Answers
+<Layers A/B/C in a table>
+
+## Files Created
+| Path | Bytes | Generated by |
+|------|-------|--------------|
+| ... | ... | ... |
+
+## Services Composed
+<table of services with port + UI URL + default credentials, sourced from .agents/skills/docker-compose-recipes/>
+
+## Next Steps
+1. `cp .env.example .env` and review credentials.
+2. `pnpm install` (or your chosen package manager).
+3. `pnpm dev:up` to bring up all services. Wait for healthchecks.
+4. Open MailHog UI at http://localhost:8025 to confirm email capture is wired.
+5. `/dw-create-prd` to draft the first feature.
+6. After your first substantial commit, run `/dw-analyze-project` to enrich `.dw/rules/`.
+```
+
+## Flags
+
+| Flag | Behavior |
+|------|----------|
+| (default) | Run phases 0 → 4 with the human approval gate at the end of Phase 2 |
+| `--dry-run` | Run phases 0 → 2, write the one-pager and report (`status: PLANNED`), do NOT execute Phase 3 |
+| `--no-git` | Skip the initial commit in Phase 3.10 |
+| `--no-ci` | Skip the GitHub Action in Phase 3.7 |
+
+## Critical Rules
+
+- <critical>NEVER bypass the Phase 2 approval gate. If invoked in a non-interactive context, abort with: "/dw-new-project requires an interactive approval; rerun with --dry-run to plan-only."</critical>
+- <critical>NEVER run `create-*` tools outside `{{TARGET_DIR}}`. Each command's CWD is the target dir.</critical>
+- <critical>If MailHog/Mailpit/smtp4dev was selected, NEVER also wire a real SMTP into dev. The dev compose ALWAYS captures.</critical>
+- <critical>If a `create-*` tool fails, STOP execution. Do not skip ahead to compose generation — partial scaffolds confuse later commands.</critical>
+- Do NOT pin Node/Python/.NET/Rust SDK versions inside the project unless the user asks; rely on `package.json` engines / `pyproject.toml` / `global.json` / `rust-toolchain.toml` to express intent without forcing.
+- Do NOT bake secrets into any generated file. `.env.example` has dev defaults only; real values live in untracked `.env`.
+
+## Error Handling
+
+- Docker missing → warn in Phase 0, allow `--dry-run`; abort `--execute` with install instructions.
+- `create-*` tool unreachable (npm registry down) → abort the bootstrap with the exact command + exit code; do NOT half-scaffold.
+- User picks MongoDB → note "MongoDB recipe not bundled in v0.8.0; we'll add app dependencies but you'll need to wire the service manually". Continue.
+- User picks Caddy → same: note as not in bundled recipes; continue without compose service.
+- Port already bound on host → suggest the override env var and continue; do not pick a different port silently.
+- Working tree contains files other than the allowed set → list them and ask explicitly before proceeding.
+
+## Integration With Other dw-* Commands
+
+- **`npx dev-workflow init`** is a hard predecessor. Run order: `init` → `/dw-new-project` → `/dw-create-prd`.
+- **`/dw-create-prd`** is the suggested next step after a successful bootstrap.
+- **`/dw-analyze-project`** should run after the first substantial commit to enrich `.dw/rules/` — the bootstrap leaves a minimal seed.
+- **`/dw-deps-audit --scan-only`** can run immediately after bootstrap to confirm no vulnerable deps shipped from the `create-*` templates.
+- **`/dw-security-check`** runs as part of the standard PRD pipeline after the first feature lands.
+- **`/dw-dockerize`** is the sister command for retrofitting Docker into an existing project that didn't start with this command.
+
+## Inspired by
+
+`dw-new-project` is dev-workflow-native. The interview pattern borrows from `/dw-create-prd` (Socratic clarification, conditional branching by prior artifact). The execution discipline (per-phase verification, atomic gate before mutation) borrows from `/dw-deps-audit` and `/dw-security-check`. The compose-composition logic is delegated to the `docker-compose-recipes` bundled skill. The wrap-the-official-tool philosophy was confirmed via `/dw-find-skills` against the `npx skills` ecosystem on 2026-04-28 — no skill there matched the "interview + multi-stack scaffold + dev compose" combination at sufficient quality.
+
+</system_instructions>

package/scaffold/en/templates/project-onepager.md

@@ -0,0 +1,129 @@
+---
+type: project-onepager
+schema_version: "1.0"
+status: draft
+date: YYYY-MM-DD
+shape: frontend | backend | fullstack
+languages: []
+frameworks: { web: '', api: '' }
+package_manager: ''
+monorepo: ''
+services: []
+---
+
+# Project: [Project name]
+
+## Purpose
+
+[One paragraph in product language. Who will use this, what problem it solves, what success looks like in 6-12 weeks. Avoid implementation language.]
+
+## Stack Selected
+
+| Layer | Choice | Rationale |
+|-------|--------|-----------|
+| Shape | frontend / backend / fullstack | [why this shape — single product surface, API for partners, etc.] |
+| Frontend | Next.js / Vite+React / n/a | [why this framework — SSR needs, SPA simplicity, etc.] |
+| Backend | FastAPI / ASP.NET Core minimal / Axum / Fastify / n/a | [why this framework — team expertise, ecosystem, latency targets] |
+| Database | Postgres / MySQL / SQLite / MongoDB / none | [why this DB — relational needs, JSON-heavy, transactional, etc.] |
+| Cache | Redis / Memcached / none | [why or why not] |
+| Queue | BullMQ / Celery / RabbitMQ / LocalStack SQS / none | [why or why not + sync vs async workers] |
+| Email — dev | MailHog (default) / Mailpit / smtp4dev / none | [usually MailHog — capture only, never sends real mail] |
+| Email — prod | SMTP / SendGrid / Resend / Postmark / SES / none | [why this provider — volume, deliverability, cost] |
+| Object storage | S3 / MinIO (dev) / GCS / none | [why or why not] |
+| Search | Meilisearch / Typesense / Elasticsearch / none | [why this engine — features, scale, simplicity] |
+| Observability | Sentry / OTel + Jaeger / none | [why this approach — error tracking only, full tracing, etc.] |
+| Reverse proxy | Traefik / Caddy / none | [usually only needed for multi-host dev or prod] |
+| Auth | NextAuth / Lucia / Clerk / fastapi-users / dotnet Identity / custom JWT / none | [why this approach — social login needs, B2B, etc.] |
+| Linter / formatter | Biome / ESLint+Prettier / Ruff+Black / dotnet format / cargo fmt+clippy | [team preference] |
+| Package manager | pnpm / npm / yarn / poetry / uv / cargo / dotnet | [team preference] |
+| Monorepo orchestrator | pnpm workspaces / npm workspaces / Turborepo / Nx / n/a | [only for fullstack — caching/build needs] |
+| CI | GitHub Actions / none | [usually GitHub Actions; opt out only for non-public repos] |
+
+## Services & Infra
+
+[Generated services from the docker-compose-recipes skill. Filled by /dw-new-project.]
+
+| Service | Port (host) | UI | Default credentials |
+|---------|-------------|----|--------------------|
+| postgres | 5432 | — | POSTGRES_USER=app, POSTGRES_PASSWORD=app, POSTGRES_DB=app |
+| redis | 6379 | — | (no auth in dev) |
+| mailhog | 1025 (smtp), 8025 (UI) | http://localhost:8025 | (no auth) |
+| ... | ... | ... | ... |
+
+## Architecture Diagram
+
+```
+[ASCII diagram of the chosen shape. Examples below.]
+
+# Frontend-only
+[ Browser ] -> [ Next.js (apps/web) ]
+
+# Fullstack
+[ Browser ] -> [ Next.js (apps/web) ] -> [ FastAPI (apps/api) ] -> [ Postgres ]
+                                                                |-> [ Redis ]
+                                                                |-> [ MailHog ]
+
+# With observability
+... -> [ FastAPI ] -> { OTLP } -> [ Jaeger ]
+```
+
+## Generated Files
+
+[Filled by /dw-new-project after Phase 3 — list of files created with their sources.]
+
+```
+{{TARGET_DIR}}/
+├── apps/
+│   ├── web/                      (created by `pnpm create next-app`)
+│   └── api/                      (inline scaffold — FastAPI)
+├── packages/
+│   └── shared/                   (created by /dw-new-project)
+├── docker-compose.dev.yml        (composed from .agents/skills/docker-compose-recipes/)
+├── .env.example                  (consolidated from selected services)
+├── .gitignore                    (per stack)
+├── .dockerignore                 (per stack)
+├── .github/workflows/ci.yml      (CI matrix per app)
+├── package.json                  (root scripts: dev:up/down/logs/reset)
+├── pnpm-workspace.yaml           (if pnpm workspaces)
+├── turbo.json                    (if Turborepo)
+├── README.md                     (Quick Start + Local Dev port table)
+└── .dw/
+    ├── rules/index.md            (seeded — enrich later via /dw-analyze-project)
+    └── spec/projects/<name>.md   (this file)
+```
+
+## MVP Scope
+
+[The smallest first feature you'll ship. Thought as user stories — this should drive the first /dw-create-prd run.]
+
+- As a [persona], I can [action] so that [benefit]
+- As a [persona], I can [action] so that [benefit]
+
+If you don't have a first feature in mind yet, that's OK — leave a placeholder and run /dw-create-prd when ready.
+
+## Not Doing (explicit)
+
+[Tempting items deferred. Forces scope discipline.]
+
+- **[item 1]** — reason: [out of v1 because...]
+- **[item 2]** — reason: [could become v2 if hypothesis X validates]
+
+## Key Assumptions
+
+- **[assumption about users / market / scale]** — test: [how this assumption is validated]
+- **[assumption about latency / volume / SLAs]** — test: [load profile, target metric]
+
+## Open Questions
+
+[Things this one-pager cannot answer alone. Resolve before /dw-create-prd or escalate to a stakeholder.]
+
+- [question 1]
+- [question 2]
+
+## Next Step
+
+Pick ONE:
+
+- **`/dw-create-prd`** — when you have a first feature in mind and want to draft the PRD on top of this stack
+- **`/dw-analyze-project`** — after the first substantial commit, to enrich `.dw/rules/` with module-level conventions
+- **`/dw-deps-audit --scan-only`** — to confirm no vulnerable deps shipped from the `create-*` templates