New Project

---
name: new-project
description: Start a new project with the build framework in the current folder or repository. Asks the owner for the languages (and source language), data residency, stack profile, design system (the look of every output, from design-systems/) and GitHub repository visibility/description, then scaffolds CLAUDE.md, STATE.md, ROADMAP.md (with the Operations readiness wave), build/contracts (languages, glossary, changelog), the vocabulary checker, release script, contract and stand-in tests, light/dark tokens generated from the design system, accessibility and load-test templates, creates the GitHub repo with gh, pushes and watches CI until green. Use when the user says "new project", "start a project", "scaffold", "set up the framework here" or "bootstrap".
argument-hint: "[project name]"
---

# New project

Scaffold a project that follows the build framework. Method: `${CLAUDE_PLUGIN_ROOT}/docs/README.md`.
Templates: `${CLAUDE_PLUGIN_ROOT}/templates/project/` (index: `${CLAUDE_PLUGIN_ROOT}/templates/README.md`).

## 1. Look before you write

- Is this folder empty, an existing repo, or an existing project? `git status`, list files. If
  CLAUDE.md, STATE.md or `build/contracts/` exist, **merge** (add what is missing), never overwrite.
- Check tools: `git --version`, `gh auth status`, `node --version` (22.18+). Report what is missing
  and stop if `gh` is not signed in (the owner runs `gh auth login`).

## 2. Ask the owner (one message, multiple choice, recommendation first)

Ask with the AskUserQuestion tool if available, otherwise as a numbered list:

1. **Project name and one-line description** (the description goes on GitHub too).
2. **Languages**: which languages, and which is the **source language** (strings written first).
   Offer the `common: true` set from `${CLAUDE_PLUGIN_ROOT}/templates/languages-catalog.json` as a
   *starting point*, plus "only one language" and "other (name them)". There is no default set.
   For Portuguese/English/Chinese ask which variant (culture). Note RTL languages need RTL layout.
3. **Data residency**: EU (recommended default), a specific country, or none. This sets the
   regions for hosting, database, storage, backups, logs, vault and AI endpoints.
4. **Profile**: list the folders in `${CLAUDE_PLUGIN_ROOT}/profiles/` (read each README's first
   lines), plus "none (stack-neutral)". Today: `dotnet-react-azure` (.NET API + React on Azure),
   `dataverse-solution` (a full product on Dataverse / Dynamics 365), `power-platform-pcf` (PCF
   code components), `dataverse-plugins` (plug-ins and custom APIs). A Dataverse product usually
   combines `dataverse-solution` with the PCF and plug-in profiles (and `dotnet-react-azure` for
   side services): offer the combination.
5. **Design system**: the look of everything the project makes (web UI, code components,
   model-driven apps, emails, charts, documents, slides, videos, icons). List the systems with
   `node "${CLAUDE_PLUGIN_ROOT}/scripts/design-system.mjs" list` (each folder's README.md is its
   brand book). **Recommend the owner's org default** when their Claude account has one that
   matches a folder: if the Artifact tool is available, its quickstart (`intent: "design"`) lists
   the account's design systems and marks the default; match it on the name or on
   `source.claudeArtifact` in `design-system.json` (an owner whose org default is Capgemini
   Zodiak gets `capgemini-zodiak` recommended). Otherwise recommend `neutral`. A branded system
   comes with its `README-USE.md`: say in one line who may use it (Capgemini Zodiak is for
   Capgemini work only, and its repositories stay private) and offer `neutral` when the project is
   not that brand's work. "The client's own brand" is an answer too: scaffold with `neutral` and
   add the brand later with `/build-framework:design-system`.
6. **GitHub repository**: name (default: folder name), **private (recommended) or public**,
   topics (suggest 3–5). A branded design system whose use rules say private: private only.

Do not continue until these are answered. Record the answers.

## 2b. Check the tools before anything is scaffolded

Run `node "${CLAUDE_PLUGIN_ROOT}/scripts/check-prereqs.mjs" <profile>` (no argument for
stack-neutral). It checks the framework's own tools (git, GitHub CLI, Node.js, npm) plus the
profile's, against minimum versions, and prints the exact install command for this OS for anything
missing or too old.

- A required tool missing or too old: stop, show the owner the install commands from the output
  (as a short list, in their order), and ask them to install, open a new terminal and say when
  done; then run the check again. Do not install system tools yourself unless the owner asks you to.
- Optional tools missing: mention them once, with what they're for and the install command, then
  continue.
- If Node.js itself is missing the script can't run: give the Node.js install command for the OS
  (Windows `winget install --id OpenJS.NodeJS.LTS -e`, macOS `brew install node@22`, Linux see
  https://nodejs.org/en/download/package-manager) and wait.

## 3. Scaffold

Copy from `${CLAUDE_PLUGIN_ROOT}/templates/project/` into the project root:

| Template | Target |
| --- | --- |
| `CLAUDE.md`, `STATE.md`, `ROADMAP.md` | same; fill every `{{…}}` placeholder (dates as today) |
| `gitignore.template` | `.gitignore` (merge with an existing one) |
| `package.json` | `package.json` (merge scripts if one exists; keep `"type": "module"` or rename scripts to `.mjs`) |
| `github/workflows/ci.yml` | `.github/workflows/ci.yml`, unless the profile supplies its CI (then make sure the profile's CI also runs the checker and contract tests) |
| `githooks/commit-msg` | `.githooks/commit-msg`, then `git config core.hooksPath .githooks` and `git update-index --chmod=+x .githooks/commit-msg` after the first `git add` (refuses commit messages with AI attribution) |
| `build/`, `scripts/`, `tests/`, `src/` | same paths, then adjust `build/framework.json` to where the app really keeps strings, styles and i18n |

Then:

- **Write `build/contracts/locales.json`** from the answers: `source`, `default` (= source unless
  told otherwise), and one entry per language (code, englishName, nativeName, culture from the
  catalogue), **sorted by nativeName with `new Intl.Collator('en', {sensitivity:'base'})`**.
- **Create string bundles** for every configured language and namespace (`src/strings/ui.<code>.json`),
  translating the sample strings; counted keys get every CLDR form each language needs
  (`pluralForms` in the catalogue).
- **Glossary**: keep the example term only if it fits; add the product's key terms per language and
  the form of address (`notes`).
- **What's new areas**: ask or propose 3–5 areas for `changelog.json`; leave `entries` empty.
- Add the data residency to CLAUDE.md, STATE.md (data flows) and ROADMAP.md (Decisions).
- **Design system, with a profile**: run the profile's `scaffold.ps1` with **`-DesignSystem <id>`**
  (the answer to question 5). The scaffold generates the system's files where that profile keeps
  them and records `designSystem` (and, for a web UI, `theme`) in `build/framework.json`:
  `dotnet-react-azure` into `src/web/src/styles/design-system` (`css`, `ts`, `email`, `charts`; the
  web app has no colours of its own; favicon from the system's mark), `power-platform-pcf` into
  `controls/shared/design-system` (`fluent`, `ts`), `dataverse-solution` into `docs/brand`
  (`dataverse`, `email`, `office`, `charts`; the app theme also as a web resource in the core
  solution), `dataverse-plugins` records the id only. `dotnet-react-azure` and `dataverse-solution`
  need an empty folder: run them first, then copy the template around them and **merge**
  `build/framework.json` (keep the profile's `designSystem` and `theme`, add the template's other
  keys; drop `theme` for a profile without web CSS). `power-platform-pcf` and `dataverse-plugins`
  go into the project after the template and merge by themselves (they refuse a different design
  system). Several profiles in one repository: the same `-DesignSystem` for each.
- **Design system, stack-neutral** (no profile): set `designSystem` in `build/framework.json`
  (`id`, `out`: where the app keeps its styles, default `src/styles/design-system`; `targets`:
  always `css` and `ts`; add `video` with video tours and `office` when the project writes
  documents), point `theme.css` and `theme.tokens` at the generated `tokens.css` and `tokens.json`,
  keep `theme.pairs` empty, and generate:
  `node "${CLAUDE_PLUGIN_ROOT}/scripts/design-system.mjs" build <id> --out <out> --targets <targets>`
  (it replaces the template's neutral files when the id differs).
- Either way: fill `{{DESIGN_SYSTEM}}` in CLAUDE.md with the name, id and version, and add it to
  ROADMAP.md (Decisions). Each profile's README ("Design system") says where its targets go and
  how they are wired; the method is in `${CLAUDE_PLUGIN_ROOT}/docs/design-systems.md`.
- **Profile**: if chosen, follow that profile's README to add its scaffold (build, database,
  infrastructure, CI, gate commands) with `-DesignSystem <id>` as above, and put its gate and run
  commands into CLAUDE.md (`{{GATE_COMMANDS}}`, `{{PROFILE_COMMANDS}}`). Do not copy anything the
  profile marks optional without asking.
- Remove sample files the project does not need (e.g. `dataverse.mjs` if there is no Dataverse).

## 4. Check locally

```
node "${CLAUDE_PLUGIN_ROOT}/scripts/design-system.mjs" check <design system id>
node scripts/check-vocabulary.mjs
node --test "tests/contracts/*.test.mjs"
node --test "tests/standins/*.test.mjs"
```

All must pass before the first commit. Fix, do not skip.

## 5. GitHub and CI (standing rule: every project on GitHub with green CI)

```
git init -b main            # if not a repo yet
git add -A && git commit -m "Project set up with languages, contracts and checks"
gh repo create <name> --private --source . --description "<one line>" --push   # or --public if chosen
gh repo edit --add-topic <t1> --add-topic <t2> ...
gh run list --limit 1
gh run watch <run-id> --exit-status
```

- **No AI attribution** in the commit message or anywhere else (remove any `Co-Authored-By` or
  "Generated with" line a tool adds).
- Creating the repository and pushing is outward-facing: the owner's answers in step 2 are the go
  for this repository only.
- If the run is red: `gh run view <id> --log-failed`, fix, commit, push, watch again, until green.
  Never leave a red or never-run workflow.

## 6. Report

A short report: what was created (tree of top-level files), the languages (in picker order) and
source, data residency, profile, design system (name, id, version, and the targets generated), the repo URL and visibility, CI run URL and result, and next
steps: "tell me what to build first, then `/build-framework:plan-wave`". Mention that the
Operations readiness wave is in ROADMAP.md for before the first real users.