# Project Start > Use ONLY when the user explicitly asks to start or initialize a new Greenfield project, or to plan the next wave of features (update the Roadmap, add draft Feature Specs) for an existing project that already has trustworthy documents. Runs understand-first context reading, a focused interview, project documents (README, PRODUCT, ARCHITECTURE, TESTING, and applicable extras), a Feature Roadmap, and draft Feature Specs. MUST NOT be used to implement a feature (project-dev), to take over an undocumented Brownfield repository (project-onboard), or to independently verify the current project state against its documents (project-verify). - Skill: `maoyuanyang/project-start` (Agent Skill, multi-file: 7 files) - Install (CLI): `npx skillmds@latest add maoyuanyang/project-start` - Raw SKILL.md: https://api.skillmd.com/api/skills/maoyuanyang/project-start/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Product & Planning - Author: MaoyuanYang (https://skillmd.com/u/maoyuanyang) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/maoyuanyang/project-start --- # project-start Turn a rough project idea into the project-level documents a coding agent needs before feature work: product and architecture documents, a Feature Roadmap, and draft Feature Specs. The output of this skill is documents, not code. Feature implementation belongs to `project-dev`. For an existing project that already has trustworthy documents, the same workflow applies when the user asks to plan the next wave of features: skip what already exists, interview only about the new direction, and update the Roadmap and draft Specs. ## Workflow ```text Project Idea ↓ 1. Understand context ↓ 2. Interview the user ↓ 3. Write project documents ↓ 4. Create the Feature Roadmap ↓ 5. Write draft Feature Specs ↓ 6. Publish to GitHub (optional) ↓ 7. Stop ``` ## 1. Understand context first Before asking the user anything, collect what is already determinable: - Everything the user has already said or provided. - The current directory: existing files, notes, configs, prior work. - Stated technical or business constraints. Do not ask about anything you can answer from these sources. If the directory already contains material business code, stop and recommend `project-onboard` instead. If scanning the templates leaves no user-owned gap — the idea plus this context is enough to write honest documents — skip the interview or keep it to one short confirmation round. ## 2. Interview the user The templates define what must be understood; the interview fills the user-owned gaps. Scan the templates section by section and fill in everything already determinable — what the user said, what the directory shows, and low-risk engineering judgment. Then ask only about the unresolved user-owned gaps (product goals, users, core scenarios, scope, business rules, behavior preferences, success criteria, hard constraints); never guess their answers. See [references/interview.md](references/interview.md). The document language is the one user-owned gap the scan cannot fill: English is the default, and the user may prefer another language. Confirm it once — during the interview, or in the short confirmation round when the interview is skipped — and write every document (`README.md`, `docs/`, `specs/`) in the confirmed language. On a project that already has trustworthy documents, keep their language instead of asking. Collaboration is the other question the scan cannot answer. When the environment offers it — a GitHub remote plus an authenticated `gh` CLI, checked before asking — ask whether to enable GitHub collaboration: issues for the roadmap features, pull requests for delivery, CI as verification evidence, a milestone for the wave, and optionally a Projects board mirroring the Roadmap. Record the decision; it becomes the `Collaboration` line in `specs/ROADMAP.md` (`## Tracking`) and authorizes the §6 publish step. With no GitHub environment, skip the question — the project simply runs locally. See [references/github-flow.md](references/github-flow.md). Before writing documents, briefly summarize the key decisions back to the user and let them correct you. This one checkpoint catches most misunderstandings cheaply. ## 3. Project documents Write the project documents using the templates in `assets/`. Templates define the sections to think about; repository context, interview answers, and engineering judgment fill them in. A section that genuinely does not apply can be deleted. Write every document in the language confirmed in step 2 — English by default. ```text README.md what the project is, how to run it docs/PRODUCT.md goal, users, use cases, scope docs/ARCHITECTURE.md system shape, modules, data flow, key decisions docs/TESTING.md strategy, levels, key commands docs/DATABASE.md only when the product persists data docs/API.md only when the product exposes an API docs/FRONTEND.md only when the product has a UI ``` Create only the documents that apply. Do not create empty files for symmetry: a CLI tool needs no `FRONTEND.md`, a pure frontend needs no `DATABASE.md`. Keep each document short and true; a precise one-page document beats a speculative ten-page one. ## 4. Feature Roadmap Create `specs/ROADMAP.md` (see `assets/roadmap.template.md`): an ordered table of the features that together deliver the product's core value, with a draft spec file for each (`specs/F001-.md`, `F002-...`). Start small — the roadmap should show the shortest credible path to a usable product, not an exhaustive wish list. Mark one feature as `Next`. Record the interview's collaboration decision in the Roadmap's `## Tracking` section; in GitHub mode the Features table carries an `Issue` column and gains the `In Review` status. ## 5. Draft Feature Specs Write a draft spec for each roadmap feature using `assets/feature-spec.template.md` (the same template `project-dev` later refines). Drafts fill in what is already decidable — goal, background, rough requirements — and record the rest as open questions for `project-dev` to resolve with the user. Do not invent answers to user-owned questions here; leave them in `Open Questions`. ## 6. Publish to GitHub (optional) In GitHub mode — collaboration enabled and the environment ready — publish the plan: create one issue per roadmap feature (the spec's Goal summary plus a link to the spec file), a milestone for this wave, and, if the user chose it, a Projects board whose Status field mirrors the Roadmap statuses. Write the links back into the specs' `Tracking` sections and the Roadmap's `Issue` column and `## Tracking`. In local mode this step is skipped silently. ## 7. Stop When the documents, Roadmap, and draft Specs exist, stop. Tell the user what was created, which feature is marked `Next`, what was published to GitHub (when collaboration is enabled), and that implementation continues with `project-dev`. Once features are delivered, independent verification against the documents continues with `project-verify`. ## Boundaries - MUST NOT start implementing business features. This skill produces documents. - Non-business scaffolding is acceptable when needed to make documents honest (e.g. initializing a package so `README` build commands are real, setting up an empty test runner so `TESTING.md` commands run). Keep it minimal. - MUST preserve unrelated user changes in the worktree. - MUST NOT perform destructive or remote actions (deleting user data, force operations, pushing, publishing, creating or updating issues, pull requests, milestones, or project boards) without explicit user authorization. The interview's collaboration decision is that authorization for the §6 publish step; every other remote action still asks.