Project Baseline Setup

---
name: project-baseline-setup
description: Scaffolds a new project with baseline engineering hygiene (README, .env.example, .gitignore covering secret files, a dependency lockfile check, an architecture-decision-record folder) and a lightweight security checklist, OR audits an existing project for what's missing and fills only the gaps. Safe to run on a brand-new empty repo or on a project someone else started, it detects what already exists and never overwrites real content. Use whenever the user says "set up a new project", "scaffold this repo", "start a new service", "add the baseline to this project", "audit this repo for missing setup", or "I just joined this project and want to check what's missing".
---

# Project Baseline Setup

One skill, two situations: a project that doesn't exist yet, and a project
that already exists but was never fully set up. Both are the same underlying
job, find what's missing against a small set of engineering and security
basics, and fill it in without disturbing anything that's already there.

## Step 1: scan first, always

Run the bundled scanner before creating or changing anything:

```bash
python3 <skill_dir>/scripts/scan_baseline.py <project_path>
```

It prints a JSON report: what project type it detected (from manifest files
like `package.json`, `pyproject.toml`, `go.mod`), and a `missing` list of
concrete gaps. It never modifies anything, it's a report.

Read the `missing` list. If it's empty, say so and stop, don't invent work.

## Step 2: fix the mechanical gaps directly

These are safe to create or fix without asking, because there's no real
content decision involved:

- **`.gitignore` missing secret patterns**: append the missing patterns
  (`.env`, `*.pem`, `*.key`, etc.) to the existing file, don't replace it.
- **`docs/adr/` directory missing**: create it with a one-line `README.md`
  explaining what an ADR is and a numbered template
  (`0000-template.md`: Context / Decision / Consequences / Status).
- **`BASELINE_CHECKLIST.md` missing**: copy
  `assets/BASELINE_CHECKLIST_TEMPLATE.md` into the project root as
  `BASELINE_CHECKLIST.md`, filling in the project name from context if you
  can infer it (e.g. from `package.json`'s `name` field).
- **Lockfile missing but a manifest exists**: don't generate one yourself
  (that requires actually installing dependencies), tell the user which
  command to run (`npm install`, `poetry lock`, `go mod tidy`, etc.) based on
  the detected manifest.
- **CI config missing**: this one needs a decision (which CI provider), ask
  or infer from context (a `.gitlab-ci.yml` already existing suggests GitLab,
  a GitHub remote suggests Actions). Offer a minimal starter workflow (lint +
  test + build) rather than a large one, it's easier to extend a small
  working pipeline than to trim a large broken one.

## Step 3: fix the content-dependent gaps with a draft, not a guess

These need real project context, don't fabricate detail you don't have:

- **README missing or a stub**: read whatever you can about the project
  (manifest `name`/`description` fields, existing source layout, package.json
  scripts) and draft a real README: what it is, how to run it locally, how
  to test it. Show the draft before writing it if the project already has
  *some* README content you'd be replacing, write directly only into a
  genuinely empty or near-empty file.
- **`.env.example` missing**: scan the codebase for environment variable
  reads (`process.env.X`, `os.environ["X"]`, `os.getenv("X")`, similar
  patterns per language) and list the ones you find, with placeholder values
  and a short comment on what each is for. If you can't find any real usage,
  say so rather than inventing plausible-looking variables.

## Step 4: report back

Summarize what you found, what you created automatically, and what still
needs a human decision (CI provider choice, whether to overwrite an existing
README, running the lockfile command). Point to `BASELINE_CHECKLIST.md` as
the ongoing record, this skill gets a project to a reasonable starting line;
the checklist is what keeps it honest as the project grows. For the fuller
set of rules behind each checklist item, see the `security-baseline` skill.

## Ground rules

- Never overwrite a file that already has real content in it. Append, create
  alongside, or ask, don't clobber.
- Never invent a decision that has real consequences (which CI provider,
  what the project is actually for) when you can ask or infer it instead.
- Re-running this skill on a project it's already touched should be a no-op
  apart from picking up genuinely new gaps, that's the whole point of
  scanning first.