start-project

name	start-project
description	Start a new self-contained project from a rough idea through a brief plain-language interview, scoped first version, implementation, preview, verification, README, and project-index update. Use when a user asks to start, create, or build a new project, app, site, tool, experiment, or script, especially when the idea is non-technical or still fuzzy.

Start a project

Turn the user's desired outcome into the smallest useful working project.

1. Understand the idea

Read the repository instructions, inspect projects/README.md, and check for a conflicting project path.

Ask only questions whose answers materially change the result. When an answer is required, prefer one short plain-language question at a time. Skip anything the user already answered and infer reversible details from context. Usually establish:

• what the user wants to accomplish and for whom;
• the essential first-version behavior;
• an example, tone, or visual direction when relevant;
• important exclusions or constraints;
• what the user expects to see when it works.

Do not ask the user to choose a framework, package, or architecture unless that choice changes the product they receive. Make reversible technical decisions using the repository defaults.

2. Set the first-version boundary

Set an internal boundary for the project name, outcome, first-version scope, notable exclusions, and how success will be checked. State it to the user when it resolves consequential ambiguity or prevents a likely surprise; otherwise proceed without another approval round.

Use a short kebab-case directory name under projects/. Never overwrite an existing path.

3. Create and build

For a browser project, default to the smallest suitable TypeScript/Vite setup with pnpm. Prefer vanilla-ts and native browser features unless the requested experience benefits materially from a framework:

pnpm create vite projects/<name> --template vanilla-ts --no-interactive

For Python, use uv. Run standalone scripts with explicit dependencies such as uv run --with rich projects/<name>/script.py; let a full Python project own its pyproject.toml and uv.lock.

Keep all dependencies and tooling inside the project. Implement one coherent, useful slice rather than speculative features. Validate untrusted input and never place secrets in tracked files.

Give every project a .quality-gate.json containing non-mutating commands that can safely block a commit. Always include named format and lint commands. Include typecheck for TypeScript, test when the project defines tests, and colors when it has color-pairs.json. Keep the underlying tools and their configuration inside the project. For a TypeScript browser project:

• enable strict TypeScript in every applicable tsconfig and provide a no-emit typecheck command;
• add a formatter check that reports drift without rewriting files;
• add a code linter with the smallest suitable project-local configuration;
• copy assets/quality-gate.web.example.json to .quality-gate.json, then remove only commands that genuinely do not apply.

The repository pre-commit hook discovers changed projects/<name>/ paths and runs each project's declared commands in order. Do not remove or disable a quality command merely to make the gate pass.

For browser projects, use native semantic HTML before generic containers or ARIA. Give the page an intelligible landmark and heading structure, use the native element that matches each interaction, label form controls, preserve keyboard operation and visible focus, and do not use color as the only signal. Add ARIA only when native HTML cannot express the required semantics.

For a visual browser project with custom colors, copy assets/color-lint.mjs to scripts/color-lint.mjs inside the project and copy assets/color-pairs.example.json to color-pairs.json. Replace the example values with named colors from the project's actual styles and declare every foreground/background combination visible in the first version, including interactive states. Use a minimum ratio of 4.5 for ordinary text and 3 for large text or non-text UI boundaries. If the project has light and dark modes, declare both values. Add a check:colors package script that runs:

node scripts/color-lint.mjs color-pairs.json

Do not add this tooling to non-visual projects or projects that keep the browser's unmodified default colors.

Give the project a concise README covering:

• what it is;
• how a person uses or opens it;
• the development and verification commands;
• its current status and known limitation, if any.

4. Verify

Install dependencies with the project's package manager. Run every relevant format, lint, typecheck, test, and build command the project defines. Leave one small runnable check for non-trivial new logic.

For a project with check:colors, run a bounded correction loop:

1. Run the color check after the first coherent visual implementation.
2. If it fails, change the actual project styles and update the manifest to match, then run the check again.
3. Repeat until it passes, for at most five total color-check runs.
4. Never pass by lowering a required ratio, deleting a real rendered pair, or changing only the manifest. If five runs do not pass, stop iterating and report the remaining failing pairs as a meaningful limitation.

Treat an invalid manifest or a run with no declared pairs as a verification failure, not as a clean result.

For a visual project, launch it and inspect the result when the active runtime provides a preview or browser capability. Otherwise perform the strongest local check available and explain how the user can open it. Fix visible errors and obvious usability problems before handoff.

5. Hand off

Replace the _None yet_ row or add one row in projects/README.md with the project link, one-sentence purpose, status, and simplest opening instruction. Update the index later only when the project is renamed or archived.

Tell the user in plain language:

• what now works;
• how to see or use it;
• what verification passed;
• any meaningful limitation or deferred request.

Do not publish, deploy, send messages, spend money, or alter an external account without explicit approval. Do not create a Git commit unless requested.