Name: SpecUI
Author: SpecUI

specui new <path> is specui init --flat with a required target name. All flags below apply to init; new accepts the subset --preset, --themes, --platforms, --agents-md, --git, and --force (defaults for a flat repo: no AGENTS.md, no git).

Presets (`--preset`)

Preset	Description
`web-app`	Default SaaS / product UI scaffolding
`mobile-app`	Mobile-first scope in front matter
`marketing-site`	Marketing / landing patterns
`dashboard-data-dense`	Dense data UI
`design-system-library`	Large catalog starter
`blank`	Minimal lists; you define components/patterns

Target and layout

Flag	Description
`--target <dir>`	Write the contract here (default: `cwd`)
`--flat`	No `.specui/` wrapper — contract at `target` root (`new` sets this)
`--force`	Overwrite an existing `.specui` or flat `SPEC.md`
`--dry-run`	Print the plan only; no writes

Product metadata

Flag	Description
`--name <string>`	Product name in `SPEC.md`
`--category <string>`	e.g. `web-app`, `marketing-site`
`--audience <string>`	Primary users

Scope

Flag	Values
`--themes`	`light`, `dark`, `high-contrast` (comma-separated)
`--platforms`	`web`, `ios`, `android`, `flutter`, `desktop`, `other`
`--density`	`comfortable`, `compact`, `dense`
`--components`	Comma list of required kebab component ids
`--patterns`	Comma list of required kebab pattern ids
`--imagery`	`photo`, `illustration`, `ai-allowed`
`--rtl`	Enable RTL requirement
`--no-rtl`	Disable RTL
`--data-viz`	Charts / data visualization in scope
`--no-data-viz`	Disable data viz

Agents and editor files

Flag	Description
`--agents-md`	Inject SpecUI block into `AGENTS.md` (default)
`--no-agents-md`	Skip `AGENTS.md`
`--agent-tools <list>`	`cursor`, `claude`, `codex`, `copilot`, `gemini`, `windsurf`
`--no-agent-tools`	Skip per-tool stub files
`--starter-kit`	Seed 2 bundled rules + 2 skills
`--seed-rules` / `--no-seed-rules`	Bundled rules templates
`--seed-skills` / `--no-seed-skills`	Bundled skills templates

If --agents-md is set and the tools list is empty, the default is cursor.

CI and git

Flag	Description
`--ci github`	Add GitHub Actions validate workflow (default when CI enabled)
`--no-ci`	Skip the CI template
`--git`	`git init` + initial commit in target
`--no-git`	Skip git (default)

Examples

Minimal blank project:

specui init --preset blank --target ./my-app --no-ci --no-git

Full agent + CI setup:

specui init \
  --name "Acme" \
  --preset web-app \
  --themes light,dark \
  --platforms web \
  --agents-md \
  --agent-tools cursor,claude,copilot \
  --starter-kit \
  --ci github

Publishable design system:

specui new ./acme-ds --preset design-system-library --git

Preview the plan before committing to anything:

specui init --dry-run --preset web-app --target /tmp/preview

Exit codes

Code	Cause
0	Success or dry-run
2	Invalid flags, missing preset, existing contract without `--force`

init reference