# Project Setup > Classify, plan, reconcile, and bootstrap software product repositories. Use when starting a greenfield web, SaaS, desktop, mobile, API, CLI, SDK, developer-tool, data, AI, browser-extension, or hybrid product; when scanning an existing software project before adopting it; or when creating or repairing product plans, design specs, backlogs, engineering guides, repository instructions, story templates, verification gates, and single, dual, or multi-agent delivery protocols. - Skill: `astropham1808/project-setup` (Agent Skill, multi-file: 18 files) - Install (CLI): `npx skillmds@latest add astropham1808/project-setup` - Raw SKILL.md: https://api.skillmd.com/api/skills/astropham1808/project-setup/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: AI & ML - Author: astropham1808 (https://skillmd.com/u/astropham1808) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/astropham1808/project-setup --- # Project Setup Set up a software product from evidence, explicit decisions, and human approval gates. Support two modes: - `greenfield`: create a product and engineering foundation before implementation. - `existing`: scan and reconcile an existing repository without overwriting its conventions. Do not apply this skill to non-software projects. ## Start with classification Ask only questions that cannot be answered from local evidence. Establish: 1. Mode: `greenfield` or `existing`. 2. Product type: web app, SaaS, desktop, mobile, backend/API, developer tool, CLI, SDK/library, data/AI, browser extension, or hybrid. 3. Lifecycle: prototype, MVP, growth, mature, or legacy modernization. 4. Surfaces: UI clients, API, workers, integrations, deployment targets, and supported platforms. 5. Source of truth: local request, Notion, issue tracker, existing documents, or a combination. 6. Artifact language. 7. Delivery model: single-agent, dual-agent, or multi-agent. Read [references/classification-and-discovery.md](references/classification-and-discovery.md) when requirements are incomplete or product type is ambiguous. Persist the result in `docs/PROJECT_PROFILE.md`. Treat this classification as provisional until the user approves it. ## Choose the workflow ### Greenfield 1. Run focused discovery and identify assumptions. 2. Research unstable or high-cost decisions using primary sources. 3. Draft the project profile and Product Plan. 4. Add a conditional Design Spec only when the product has a user interface. 5. Define architecture boundaries, technical risks, security constraints, performance budgets, and measurable success criteria. 6. Create an epic-based backlog with observable acceptance criteria and dependencies. 7. Create the Engineering Guide, repository instructions, story spec template, notes template, and verification contract. 8. Present the plan and open decisions. Wait for approval. 9. Bootstrap repository files only after approval. 10. Do not initialize Git, install dependencies, create remotes, push, or start implementation unless explicitly requested. Read [references/artifact-contracts.md](references/artifact-contracts.md) before drafting artifacts. ### Existing project scan 1. Read every applicable `AGENTS.md` and repository instruction before inspecting broadly. 2. Preserve the current branch, uncommitted changes, conventions, and generated files. 3. Inventory product docs, manifests, source layout, architecture, commands, tests, CI/CD, deployment, data, API contracts, security, observability, and release process. 4. Infer product type and lifecycle from evidence. Mark uncertainty instead of guessing. 5. Classify each setup area as `Adopt`, `Adapt`, `Add`, `Avoid`, or `Unknown`. 6. Produce a gap analysis with evidence, impact, and the smallest proposed change. 7. Wait for approval before creating or modifying repository files. 8. Add only missing artifacts. Reconcile existing files surgically and never replace them with generic templates. Read [references/existing-project-scan.md](references/existing-project-scan.md) before scanning. ## Select conditional artifacts Always consider: - `docs/PROJECT_PROFILE.md` - `docs/PRODUCT_PLAN.md` - `docs/BACKLOG.md` - `docs/ENGINEERING_GUIDE.md` - `AGENTS.md` - `specs/_TEMPLATE.md` - `notes/_TEMPLATE.md` - a deterministic project verifier Create `docs/DESIGN_SPEC.md` for products with a user interface. Tailor its concerns: - Web/SaaS: responsive behavior, accessibility, browser support, SEO when relevant, authentication, and deployment. - Desktop: native integration, platform conventions, installers, updates, filesystem access, and cross-platform verification. - Mobile: platform conventions, permissions, offline behavior, app stores, and device testing. - API/backend: omit UI design unless an admin surface exists; define schemas, versioning, authentication, rate limits, errors, and observability. - CLI: define command grammar, exit codes, stdout/stderr, non-interactive behavior, and shell/platform compatibility. - SDK/library: define public API, compatibility, packaging, examples, migration policy, and release guarantees. - Data/AI: define data contracts, evaluations, latency, cost, privacy, failure modes, human control, and model/provider boundaries. - Hybrid: combine only the relevant contracts and identify shared versus platform-specific layers. Use the templates under `assets/` as starting points, not as authority over existing project evidence. ## Configure delivery Read [references/delivery-models.md](references/delivery-models.md) before recommending an agent workflow. Default to the smallest adequate model: - Single-agent for small, coupled, exploratory work. - Dual-agent for one important story requiring independent review. - Multi-agent for multiple ready, independent stories with reliable verification. For multi-agent delivery, keep one implementation owner, branch, and worktree per story. Reviewers and verifiers remain read-only unless ownership is explicitly transferred. Keep PR creation and merge as human gates. When a remote source such as Notion is used, fetch the narrowest sufficient story context once, record its ID or URL in the local spec, and make the local spec the execution contract. ## Bootstrap safely After approval, run: ```bash python3 /scripts/bootstrap_project.py \ --target \ --project-name "" \ --mode \ --product-type \ --design-spec \ --instructions \ --dry-run ``` `--instructions` picks the repository instruction file: `agents` writes `AGENTS.md` (the default), `claude` writes `CLAUDE.md`, and `both` writes `CLAUDE.md` plus an `AGENTS.md` symlink pointing at it so one set of rules serves both agents. Use `both` when Claude Code will also work the repository. Review the dry-run. Run again without `--dry-run` only when the listed files are in scope. The script refuses to overwrite files. Validate with: ```bash python3 /scripts/validate_setup.py --target ``` Validation accepts either instruction file. Treat it as a completeness check, not proof that product decisions are correct. ## Scaffold the verifier The delivery flows treat `scripts/verify-project.sh` as the only definition of done, and `bootstrap_project.py` does not write it. Scaffold a starting point from the repository's own stack markers: ```bash /scripts/init-verifier.sh --root --print # preview /scripts/init-verifier.sh --root # write it ``` The script detects Rust, Node.js with its lockfile's package manager, Go, Java with its Maven or Gradle wrapper, Python, and .NET, writes `scripts/verify-project.sh`, and marks it executable. It never overwrites an existing verifier without `--force`. When no stack is detected it writes a `TODO` verifier that exits non-zero, so an unconfigured project fails loudly instead of passing silently. Treat the generated commands as a draft. Replace them with the project's real checks, run the verifier once, and only then install the flow's commit gate. ## Completion contract Return: - mode, product type, lifecycle, surfaces, and source of truth; - artifacts adopted, adapted, added, intentionally omitted, or still unknown; - key product and technical decisions; - backlog shape and dependency risks; - chosen delivery model and ownership rules; - exact verification commands; - unresolved human gates; - files created or modified. Do not claim setup is complete while required decisions remain hidden, validation failed, or the user has not approved material assumptions.