---
name: starting-a-new-project
description: "Use when the workspace is empty, has no code, and the user brings a raw project idea. Normally reached via setting-up-a-project; not for an existing project."
title: starting-a-new-project
canonical_url: https://skilld.dev/gh/jetbrains/thinkrail/starting-a-new-project
last_updated: 2026-10-26T00:28:19.000Z
---

> Index of every page on this site: [llms.txt](https://skilld.dev/llms.txt)

> **Skill from skilld.dev.** Follow the user's requested action.
> If the user asked to fork this Skill, follow the fork workflow below. Do not execute the Skill instructions while copying it.
> Otherwise, follow the instructions below for this session. You do not need to install anything.
>
> If the user asked to install this Skill, run `npx skilld install jetbrains/thinkrail/starting-a-new-project`. Install writes the Skill files into the project, so every session loads them.
>
> ## Fork workflow
>
> A fork creates an editable local Skill with its original author and licence. The request authorizes copying and local installation.
> 1. Check `./skills/starting-a-new-project`, the project lockfile, and selected Agent targets together. If the local directory or installed Skill exists, stop. Never overwrite an existing directory or Agent target.
> 2. Read [source metadata](https://skilld.dev/api/v1/skills/jetbrains/thinkrail/starting-a-new-project) once. Use sourceUrl, sourceCommit, skillPath, sourceGone, and license. If the source is gone or its path is missing, stop. If license is null, read licence files at the source commit.
> 3. Fetch only the source commit into a temporary Git repository. Do not clone full history. Derive repository_url from sourceUrl, including repository renames. If sourceCommit is absent, resolve the sourceUrl ref once. Set source_commit to that actual commit. Run these commands in one shell call:
>
> ```sh
> git init --quiet "$temporary_dir"
> git -C "$temporary_dir" fetch --quiet --depth=1 "$repository_url" "$source_commit"
> git -C "$temporary_dir" checkout --quiet --detach FETCH_HEAD
> ```
>
> Read applicable licence declarations and notices at that commit. If copying is not permitted, report the restriction and stop.
> 4. Inspect source entries together, then copy the directory containing skillPath into `./skills/starting-a-new-project`. Use the user's path if selected. Keep the original SKILL.md, relative links, scripts, binary assets, and executable modes. Exclude .git metadata. Reject symlinks and paths outside the Skill directory. After checking entries, use cp -a where available. A regular source directory needs no custom copy script. Do not save this page wrapper as SKILL.md.
> Preserve author credit, notices, and applicable licence files from repository or parent directories. Add PROVENANCE.md with the Skill page, source URL, actual commit, original path, and licence. Retain any existing PROVENANCE.md and record new provenance separately. Batch source inspection, copying, and provenance work where practical.
> 5. In the project root, run `skilld install ./skills/starting-a-new-project --mode copy --plain`. If skilld is unavailable, use `npx skilld install ./skills/starting-a-new-project --mode copy --plain`. This known command needs no help lookup. Install does not support --json. Use detected Agent targets, or add --agent for the targets the user selected. Install the local path, never the upstream selector. If installation fails, preserve the local copy and report the exact failure.
> 6. Confirm the local lockfile source and installed Agent copies once. Report the local path, actual commit, and Agent targets. After edits, reinstall the same local path. Upstream updates must not replace it. Do not publish or push unless the user asks.

# Starting a new project

The workspace is empty: no code, no decisions. Turn the user's idea into one clear, living product
document — `goal-and-requirements.md`. Later features, behavior changes, and bug fixes go through
`brainstorming`.

**Hold the writing-specs bar.** Read that concept skill before saving anything — it carries the
short / honest / on-rails rules and the goal-doc shape every section you save must meet.

## Method

1. **Build on what's already said.** Never re-ask what the request already told you.
2. **Infer, then confirm** — propose a concrete draft and let the user correct it; a suggestion beats an
   open question. Compose `ask_user_question` rounds per the **asking-user-questions** concept skill
   (read it before the first round — it carries the round, option, confirmation, and degradation norms).
3. **Smallest useful first build.** It is smaller than the user expects; every capability in it must
   justify itself. Ideas cut from it are handed back to the user, not saved (see writing-specs).
4. **Save incrementally.** Create the file as soon as the first section is settled, then add each
   confirmed section in template order. Don't batch; don't invent unconfirmed content.
5. A skipped question is not a blocker — proceed on the current model and note real gaps inline.

## Working model (infer from the request; never ask these directly)

```
audience:   personal | public | both        domain: what space this is in
tech:       stack mentioned, or null         scope:  small | large
depth:      light | standard | full          creator_is_user: does the maker use it?
```

`depth` scales the document: `light` = a one-liner idea → a few lines; `full` = named competitors /
multiple user types → a full PRD. It can only grow during the conversation, never shrink.

## Fast path — pre-filled brief

If the request already reads like a spec (several headings or a multi-section brief), parse it, treat those
sections as **confirmed**, save them immediately, and only pursue what's genuinely missing and required by
`depth`. Don't ask the user to confirm what they already wrote. Save in the goal-doc shape, not the
brief's: a version or roadmap split (`MVP` / `v1` / `v2` / later) becomes Capabilities for what is in
scope and Non-Goals only for what the brief rules out by decision; the rest goes back to the user
unsaved (writing-specs). The one always-offered extra is alternatives research (below).

## Flow

1. **Orient** — one line: "Let's nail the goal and scope, then I'll save it as `goal-and-requirements.md`."
2. **Overview** — infer it (`depth`-sized: a sentence → a paragraph naming what it replaces) and confirm.
3. **Problem** — one tailored question referencing the domain (never generic); turn the answer into a
   statement (who / what they do today / the specific breakdown) and confirm. Skip if the Overview already
   implies it.
4. **Route** from the model — don't ask "who's this for" unless genuinely ambiguous:
   personal / first-person pain / `depth=light` → **Personal spec**; public / named users / `depth=full`
   → **PRD**.
5. **Elicit the branch's sections** (below), inferring and confirming each, saving as you go.
6. **Research alternatives** (always offered, never forced): `web_search` + `fetch_content` for the
   closest open-source projects / products, then offer to add an **Alternatives Considered** section
   (name, one-line gap, URL). On a pre-filled brief, ask permission first.
7. **Review** the full draft in plain markdown and confirm, then finalize.

### Personal spec (sections)

`# Title` + one-line tagline · **Overview** · **Problem** · **Capabilities** (only what the tool is useless
without) · **Tech Notes** (the stack, once chosen).

### PRD (sections)

`# Title` + tagline · **Overview** · **Problem Statement** · **Target Users** (roles, not demographics) ·
**Jobs to Be Done** ("When [situation], I want [motivation], so I can [outcome]") · **Key User Story**
(one concrete scenario) · **Goals** (verb-first, measurable) · **Non-Goals** · **Success Metrics** /
**Success Conditions** · **Capabilities** (each justified against a Goal or success condition) ·
**Non-Functional Requirements** (only if they exist) · **Technology** (Aspect | Choice |
Rationale).

Skip any section the model already answers or that `depth` doesn't warrant (`light` → skip Goals/NFRs,
binary Success Conditions instead of metrics). Reject vague goals inline: "'Better UX' isn't a goal —
'first result in under 30s' is."

## Saving

- `spec_create` once, `path: "goal-and-requirements.md"`, a slug `id`, `type: "goal-and-requirements"`,
  `title`, `status: "draft"`; replace the scaffold with the chosen template + the sections settled so far.
- `edit` to add each confirmed section in template order.
- `spec_update` `status: draft → active` once the user approves the reviewed draft.

## Next

State plainly that the spec is saved and evolves with the project. Suggest the natural next step —
sketch `architecture.md`, then build each feature through `brainstorming`. There is no board/ticket
hand-off — say it and stop: **this workflow ends here**.
