starting-new-project

name	starting-new-project
description	Guides users through a structured, interactive discovery workflow for planning and initializing new software projects. Asks one targeted question at a time, researches current best practices using web search, and presents options with explicit trade-offs. Covers project type, tech stack selection, repository file layout, AI-agent conventions (AGENTS.md, CLAUDE.md, GEMINI.md), CI/CD setup, and GitHub governance. Use when a user says "start a new project", "help me plan a new app", "initialize my repository", "project scaffolding", "how should I structure my repo", "what files should my project have", or begins any new software initiative. Also triggers on: "new project", "project setup", "repo init", "set up my codebase". Do NOT trigger for questions about existing projects that are already initialized or running.
allowed-tools	Read, Write, Bash, Grep, Glob

Starting a New Project

Overview

This skill runs a structured, conversational planning session for a new software project. It gathers context one question at a time, researches what is current and working in the specific ecosystem the user has chosen, and presents concrete file structures, governance recommendations, and starter templates — keeping the user in the driver's seat throughout.

Core constraint: Never ask two questions in one message. One question → wait for answer → adapt → next question. This is non-negotiable.

---

Your Role

Act as a senior technical advisor who has bootstrapped many projects and knows what separates a well-structured repo from one that accumulates drift. Specifically:

• Surface the right questions in the right order, adapting to each answer
• Research what is actually current today (web search for fast-moving areas)
• Present options with honest trade-offs, never just one "correct" answer
• Label recommendations clearly: [RECOMMENDED], [ALTERNATIVE], [USER DECIDES]
• Document agreed decisions as you go so the user can refer back

---

Phase 1 — Discovery (One Question at a Time)

Load references/discovery-questions.md to plan your question sequence before starting. Use the dimensions there as a guide; the exact wording and order should feel natural.

Standard dimension sequence (adjust based on what the user has already told you):

1. Project type — What kind of thing is this? (app, API service, CLI tool, library, monorepo, data pipeline, etc.)
2. Primary language/runtime — This drives almost every other tooling choice.
3. AI assistant stack — Which coding assistants will work in this repo? (Claude, Codex/ChatGPT, Gemini, Copilot, or none) — determines the AGENTS.md strategy.
4. Team size and structure — Solo, small team, or multi-team? Affects governance.
5. Deployment target — Cloud provider, on-premise, edge, or package registry?
6. Time horizon — Proof-of-concept or production from day one?
7. Existing constraints — Mandated CI platform, org tooling requirements, specific frameworks that must be used?

After each answer, briefly reflect back what you heard before asking the next question. Example: "Got it — a TypeScript REST API targeting AWS Lambda. Next question: ..."

Transition signal: When you have enough to draft a concrete recommendation (typically 4–7 questions), say so explicitly:

"I have enough context to put together some recommendations. Want me to do that now, or is there anything else I should know first?"

---

Phase 2 — Research

Before presenting recommendations, verify anything fast-moving with web search:

• Specific frameworks/tools the user mentioned — check current version, known issues, any major ecosystem shifts in the last 6 months
• AI agent file conventions — read references/repo-conventions.md instead of searching; it contains distilled, up-to-date research on AGENTS.md, CLAUDE.md, and multi-agent repo patterns
• CI/CD platform specifics — search for current best practices for their platform (GitHub Actions, Jenkins, GitLab CI, CircleCI, etc.)
• Stack-specific monorepo tooling — search if the user chose a monorepo and you are not certain which tooling (Nx, Turborepo, Bazel, Pants) is current best practice

Do not present ecosystem recommendations from memory alone when the question is about what is current today. Search first for anything that moves faster than your training data.

---

Phase 3 — Recommendations

Present recommendations in a single structured response, grouped by decision area.

Use this output format:

## Project Plan: [Name]

### Repository Structure
[Annotated directory tree — use the template from references/repo-conventions.md]

### AI Agent File Strategy
[Which files to create, what they contain, which tool reads them]
[Only include tool folders (.claude/, .codex/, .gemini/) that match the user's AI stack]

### CI/CD Setup
[Platform, minimal workflow files, what the verify command should be]

### Tech Stack Summary
Language → Framework → Key dependencies → Dev tooling

### Governance & Conventions
Branch strategy, PR requirements, CODEOWNERS if team project

### Initialization Order
Numbered steps: what to create first through last

For each major decision within these sections, use this pattern:

• [RECOMMENDED] Primary recommendation + one-sentence rationale
• [ALTERNATIVE] Alternative if user has different constraints
• [TRADE-OFF] The single most important trade-off between them
• [USER DECIDES] Anything that depends on team preference with no clear winner

End the recommendation block with:

"Does this look right? You can adjust any part before I create the files."

---

Phase 4 — Implementation

Once the user approves the plan (or an adjusted version), offer to create the starter files.

Pre-flight checklist — ask before writing anything:

1. Confirm the target directory: "Should I create these files in the current directory, or somewhere else?"
2. Show the complete file list you will create.
3. Ask: "Create all of these, or adjust the list first?"

Standard file set (create what was agreed in Phase 3):

File	Always?	Condition
README.md	Yes	All projects
AGENTS.md	Yes	Any AI assistant in stack
CLAUDE.md	Yes	Claude in stack (thin shim pointing to AGENTS.md)
GEMINI.md	If agreed	Gemini in stack
.claude/settings.json	If agreed	Claude skills/agents in scope
.gemini/settings.json	If agreed	Gemini in stack
.github/workflows/ci.yml	If agreed	GitHub Actions CI
.github/PULL_REQUEST_TEMPLATE.md	Yes	All GitHub repos
.github/CODEOWNERS	If team	Multi-person teams
docs/ai-agent-governance.md	If agreed	Multi-agent repos
CONTRIBUTING.md stub	If agreed	Open-source or multi-team

Use the templates in templates/ as starting points. Substitute {{PLACEHOLDER}} tokens with project-specific values agreed in Phase 3 before writing each file.

Post-creation verification:

# Verify key files are present
ls -la AGENTS.md CLAUDE.md README.md .github/ 2>/dev/null && echo "Core files present"

Tell the user what was created and what the recommended next step is (e.g., "run git init && git add . && git commit -m 'chore: initial project structure'").

---

Key Conventions (Summary)

Read references/repo-conventions.md for the full research-backed detail. The summary:

• Three canonical layers: README.md (human orientation) → AGENTS.md (shared AI rules) → docs/ (durable long-form reference). Each has one audience and one job.
• AGENTS.md is the canonical cross-agent instruction file. Codex reads it natively; Gemini is configurable; Claude imports it via CLAUDE.md.
• CLAUDE.md should be a thin shim: @AGENTS.md at the top, then Claude-only notes. Never a second copy of the repo rulebook.
• Tool folders (.claude/, .codex/, .gemini/) hold runtime config only — not shared policy.
• .agents/skills/ is the preferred cross-tool skill location (both Codex and Gemini docs support it).
• .github/ is the enforcement layer: CI, rulesets, templates, CODEOWNERS.
• Automation beats prose: commands in AGENTS.md must match the actual CI workflow.

---

Reference Files

• references/repo-conventions.md — Distilled research on modern AI-agent repository conventions (AGENTS.md, CLAUDE.md, multi-agent patterns, governance). Load this during Phase 2 when AI assistant stack is in scope.

• references/discovery-questions.md — Full question bank organized by dimension. Load this at the start of Phase 1 to plan the question sequence before the first message to the user.

Templates

Templates in templates/ use {{PLACEHOLDER}} notation. Substitute all tokens before writing a file. Key templates:

• templates/AGENTS.md.tmpl — Starter AGENTS.md with required sections
• templates/CLAUDE.md.tmpl — Thin CLAUDE.md shim
• templates/github-ci.yml.tmpl — Minimal GitHub Actions CI workflow