New Project

Plan and safely bootstrap modern software projects from typed presets and capability preferences.

Dispatch

`$ARGUMENTS`	Action
Empty	Gallery: show modes, presets, preference categories, examples; do not edit
`prefs` , `prefs list` , `catalog`	Preferences: list capability categories and defaults
`prefs validate`	Preferences: validate capability and preset catalogs
`prefs add <id>`	Preferences: explain the safe preference addition workflow
`preset list`	Presets: show curated presets and tradeoffs
`plan <name-or-path>`	Plan: read-only blueprint for a new or existing target
`init <name>` , `new <name>`	Init: new target setup after preflight, blueprint, and approval
`bootstrap <path>` , `init-existing <path>`	Bootstrap Existing: non-destructive missing-file setup
`audit <path>`	Audit: read-only scaffold and convention health report
`repair <path>`	Repair: approved additive repair based on audit findings
`doctor <path>`	Doctor: validate toolchain/config health without changing files
`docs <path>`	Docs: classify docs-lite, docs-themed, docs-interactive, or docs-product
`docs-lite <path>` , `starlight <path>`	Docs Lite: Astro Starlight static docs profile
`docs-themed <path>`	Docs Themed: Starlight plus CSS/Tailwind brand layer
`docs-interactive <path>`	Docs Interactive: Starlight plus React islands
`docs-product <path>` , `fumadocs <path>`	Docs Product: Next.js plus Fumadocs advanced docs profile
`ai <path>` , `agents <path>`	AI Instructions: AGENTS, nested AGENTS, Claude Code, OpenCode, Codex planning
`github <path>`	GitHub: CI, templates, release workflow planning
`python <name>` , `uv <name>`	Init/Plan: Python-focused preset
`node <name>` , `web <name>` , `next <name>`	Init/Plan: Node/web preset
`data <name>`	Init/Plan: Supabase, SQLite, DuckDB, notebooks preset
`aws <name>` , `agentcore <name>`	Plan: Bedrock/AgentCore planning; provider mutation is opt-in
`monorepo <name>` , `nx <name>`	Init/Plan: monorepo preset
`full <name>` , `max-free <name>`	Plan: comprehensive blueprint; apply module-by-module only
Natural language new repo/bootstrap request	Auto-classify, then ask only high-impact missing questions
Product feature request	Refuse or redirect to implementation skills
Agent or MCP server request	Refuse or redirect to `agent-conventions` or `mcp-creator`
Destructive or force request	Stop, explain risk, require file-by-file approval

Operating Flow

Classify the request as new project, existing repo bootstrap, audit, repair, preferences, docs, AI instructions, GitHub, cloud/data, or refusal.
Read
```
references/intake-and-routing.md
```
for ambiguous or natural-language requests.
Run read-only preflight before any mutating mode.
Resolve presets and capabilities from
```
data/
```
, not from ad hoc prose.
Produce a blueprint with files, commands, skipped existing files, risks, approvals, and validation.
Apply only after explicit approval, one module at a time.
Run validation and summarize created, skipped, and deferred work.

Pattern Implementation

Classification-Gating

Classify every request before acting: new project, existing bootstrap, audit, repair, preferences, docs, AI instructions, GitHub, cloud/data, or refusal. Ambiguous requests stay read-only until the missing choice is resolved.

Progressive-Disclosure

Keep

SKILL.md

as the routing contract. Load references for domain detail, data files for preferences, scripts for deterministic checks, and templates only for report rendering.

Scaling-Strategy

Add future stacks as capabilities and presets first. Change the dispatch table only when a new top-level mode is needed.

Canonical Vocabulary

Use these canonical terms exactly.

Term	Meaning
Preset	Curated setup bundle, such as `minimal` , `python-api` , `docs-lite` , or `monorepo`
Capability	Atomic setup feature, such as `python.uv` , `docs.starlight` , or `github.actions-ci`
Blueprint	Read-only project setup plan with files, commands, risks, approvals, and checks
Apply step	One approved mutation unit from a blueprint
External side effect	Cloud, deploy, release, DNS, account, or provider mutation

Reference File Index

File	Purpose	Read When
`references/workflow.md`	End-to-end safe setup flow	Mutating modes
`references/capability-model.md`	Capability schema and conflict semantics	Preference/catalog work
`references/presets.md`	Presets and tradeoffs	Preset selection
`references/preference-catalog.md`	Human-readable preference list	`prefs` , planning
`references/adding-preferences.md`	Future preference extension workflow	`prefs add` , maintenance
`references/intake-and-routing.md`	Classification and ambiguity handling	Natural language inputs
`references/scaffold-profiles.md`	Artifact matrices by preset	Blueprinting
`references/python-uv.md`	uv, uvx, pyproject, Python packages	Python profiles
`references/node-pnpm-npm.md`	pnpm, npm/npx, TypeScript, Next, Astro, Nx, Changesets	Node profiles
`references/docs-starlight-react.md`	Starlight docs-lite/themed/interactive guidance	Docs light modes
`references/docs-fumadocs.md`	Fumadocs docs-product guidance	Docs product mode
`references/design-system.md`	DESIGN.md and anti-slop design guidance	Web/docs/design profiles
`references/data-platforms.md`	Supabase, SQLite, DuckDB, Kaggle, Colab	Data/notebook profiles
`references/ai-apps.md`	Pydantic AI, LangGraph, Vercel AI SDK, Bedrock, AgentCore	AI app profiles
`references/github-ci-release.md`	Actions, releases, least-privilege CI	GitHub mode
`references/cloud-deploy-dns.md`	Vercel, Cloudflare DNS, AWS deploy gates	Cloud modes
`references/precommit-quality-gates.md`	pre-commit and CI mirroring	Quality gates
`references/conventional-commits-release.md`	Conventional Commits, Changesets, releases	Release profile
`references/ai-agent-instructions.md`	AGENTS, nested AGENTS, Claude Code, OpenCode, Codex	AI instruction mode
`references/openspec-governance.md`	OpenSpec setup and generated artifact policy	OpenSpec profile
`references/security-supply-chain.md`	Secrets, package generators, Docker, CI, supply chain	Risky modes
`references/validation-and-repair.md`	Audit, doctor, repair workflow	Audit/repair/doctor
`references/artifact-templates.md`	Skeletons and template guidance	Artifact generation

Script Index

Script	Purpose
`scripts/preferences.py`	List, validate, resolve, merge, and explain preferences
`scripts/preflight.py`	Read-only project detection and risk flags
`scripts/blueprint.py`	Build a JSON blueprint from request, preset, and capabilities
`scripts/validate_catalog.py`	Validate schemas, dependencies, conflicts, templates, and references
`scripts/validate_plan.py`	Validate blueprint safety before apply
`scripts/version_check.py`	Query package/version facts for selected packages
`scripts/doctor.py`	Verify existing scaffold health without mutations
`scripts/render_report.py`	Render report data for HTML templates

Scripts use

argparse

, JSON stdout, diagnostics on stderr, and

--help

. They must not read secret files.

Safety Gates

Preflight first for scaffold, bootstrap, repair, docs, AI, GitHub, cloud, or apply modes.
Blueprint before mutation or package install.
Skip existing files by default; overwrite requires file-by-file approval.
Preserve detected package managers unless migration is approved.
Never ask users to paste secrets into chat, and never read secret files.
Generate
```
.env.example
```
or
```
.env.template
```
, not real credentials.
Cloud, deploy, release, DNS, Docker, and account mutations require explicit provider-specific approval.
GitHub Actions default to
```
permissions: contents: read
```
; add only narrow permissions.
Docker Compose templates must avoid privileged mode, host networking, Docker socket mounts, broad host mounts, root services, and public DB binds by default.
Generated AI instructions must not bypass approvals, disable credential guards, auto-deploy, or ignore higher-priority instructions.

Critical Rules

Use the capability catalog for stack selection; do not hardcode preferences only in prose.
Distinguish
```
uvx
```
one-off tools from
```
uv run
```
project commands.
Prefer
```
pnpm
```
for new Node projects, but preserve detected npm/yarn/bun unless migration is approved.
Prefer Starlight for lightweight docs; use Fumadocs only when product/API/docs-heavy requirements justify it.
Make Tailwind v4 and shadcn/ui opt-in outside web/product profiles; add only needed shadcn components.
Never claim
```
latest
```
without live registry or official-doc evidence gathered during the run.
Do not create agents or MCP servers; redirect those requests.
Do not create branches, worktrees, commits, pushes, releases, or PRs unless explicitly requested.
Mirror local quality gates in GitHub Actions or document why CI was deferred.
Include mobile-first responsive UI requirements in web/docs/design profiles.
Update evals when dispatch modes, presets, capabilities, or safety gates change.
Keep this body under 500 lines; move details to references.

Validation Contract

Before declaring changes to this skill complete, run:

bash

python skills/new-project/scripts/check.py
uv run pytest tests/test_new_project.py
uv run python skills/new-project/scripts/preflight.py --path . --format json

After changing skill definitions, public descriptions, references, or eval behavior, invoke

docs-steward

if available.

new-project

NPX Install

Tags

SKILL.md Content