first-run

Files (1)

• SKILL.md

SKILL.md (first lines)

Generate the project profile that tailors every essentials primitive to **this** codebase: $ARGUMENTS

The agents and skills are codebase-agnostic and re-detect the stack on every run. This skill does that detection **once**, deeply, and writes the result to `.claude/essentials-profile.md` — which every primitive reads first and trusts over ad-hoc detection. Run it once per project (and again after a major stack change).

**If the profile already exists**, read it first, re-verify each line against the current repo, and update only what changed — preserve any lines the user added or edited by hand.

## Step 1 — Detect the codebase

Investigate thoroughly. Use the Explore agent (breadth: very thorough) for the sweep, then confirm specifics yourself. Determine:

- **Stack** — language(s) + version, framework(s), runtime, package manager(s), database/data layer. For the data layer, note the access idiom and what a "no row found" lookup returns (`null`/`None`/`false`/empty/throws) — the logic reviewer keys off this.
- **Commands** — the exact `test`, `lint`, `typecheck`, `build`, and `run` invocations the project actually uses (from `package.json` scripts, `Makefile`, `justfile`, `pyproject.toml`, CI config). If there's a separate E2E suite (Playwright/Cypress/Selenium), record its command too. For `run`, note the local URL/port. Prefer real project scripts over generic guesses.
- **Git** — the default branch (from `git symbolic-ref -q --short refs/remotes/origin/HEAD`, or the branch CI targets). Review agents diff against it.
- **Layout** — where source lives, where tests live and their naming pattern, where migrations live (which tool, which database dialect), where routes are declared (explicit route table vs convention-based), the templating/styling approach, where docs live, and which dirs to **skip** (vendored, generated, build output, fixtures).
- **Integrations** — inbound webhook receivers (Stripe, GitHub, Twilio, custom HMAC…): provider and handler path, or "none".
- **Deploy** — how this project ships, per environment: the trigger or command (a CI job on push/tag, `vercel --prod`, `fly deploy`, `cap production deploy`, a `make deploy`), the environment URLs, a health-check URL, the logs command, pre-deploy steps (migrations, asset build, cache clear), where env vars/secrets live, and how to roll back. Read CI config and platform files (`vercel.json`, `fly.toml`, `Procfile`, `Dockerfile`, `Capfile`, k8s/terraform dirs) and the README's deploy notes. `/deploy` refuses to guess at this.
- **Conventions** — hard rules the project states in `CLAUDE.md`, `CONTRIBUTING`, lint/formatter config, or that are obvious from the code (e.g. "data access stays out of controllers", "no inline styles", error-handling idiom, the test framework + assertion style).
- **Domain** — 1–3 sentences on what the app does and its key entities, so reviewers judge behavior, not just syntax.

**Verify, don't guess.** For each command, confirm it actually exists (the script is defined, the binary is on PATH); where cheap, run it in a list/dry-run/`--version` form. Record only what you verified; mark anything uncertain as `(unconfirmed)` rather than guessing.

## Step 2 — Write the profile

Show the user the detected summary first. On confirmation, create `.claude/essentials-profile.md` (create the `.claude/` dir if needed) using this structure — fill every section, omit lines you couldn't determine:

```markdown
# Essentials project profile
<!-- Generated by /first-run on <date> at <short commit sha>. profile-schema: 3. Read first by the essentials agents/skills. Edit freely — it's yours. -->

## Stack
- Language: …
- Framework: …
- Package manager: …
- Data layer: … ("no row found" returns: …)

## Commands
- Test: …
- Test (E2E): …
- Lint: …
- Typecheck: …
- Build: …
- Run: … (serves at: …)

## Git
- Default branch: …

## Layout
- Source: …
- Tests: … (pattern: …)
- Migrations: … (tool: …, database: …)
- Routes: … (style: explicit | convention-based)
- Templates/UI: …
- Docs: …
- Skip: …

## Integrations
- Webhooks: …

## Deploy
- Environments: … (e.g. staging → https://…, production → https://…)
- Trigger: … (e.g. merge to main runs .github/workflows/deploy.yml | manual `fly deploy`)
- Command: …
- Pre-deploy: … (migrations, build, cache)
- Health check: …
- Logs: …
- Secrets/env: … (where they're managed)
- Rollback: …

## Conventions
- …

## Domain
…
```

Omit any line that doesn't apply (no migrations, no webhooks, no E2E suite) rather than writing "none" everywhere — but keep `Webhooks: none` explicitly if you checked and found none, so the webhook reviewer can skip its search. Same for `Deploy`: if the project has no deploy mechanism (a library, a script), write `- Trigger: none` so `/deploy` knows to stop rather than detect.

## Step 3 — Make it auto-load

So the main loop (and `/commit`, `/pr`) sees it too, ensure the project `CLAUDE.md` imports it — add this line if not already present (create `CLAUDE.md` if absent):

```
@.claude/essentials-profile.md
```

## Output

Confirm the file was written, show its path, and list which primitives now consume it (all review agents, the test/docs/dependency agents, the `/test`, `/smoke-test`, and `/code-review` skills, the `/ship` workflow skills (`/plan`, `/develop`, `/deploy`, `/env-test`, and the rest), the workflows, the run-tests-on-stop hook, and the flaky-test / regression-bisect / stacktrace skills). Tell the user to re-run `/first-run` after a major stack change or a plugin update (the session-start nudge flags when the profile's schema is stale), or just edit the file directly.

> Keep the `profile-schema: 3` marker in the header comment exactly as written — the session-start hook uses it to detect profiles generated by older plugin versions. Bump it here and in `hooks/suggest-first-run.sh` together whenever the template gains or renames fields.

From jshepelsky/claude-essential-plugin, MIT.

More from jshepelsky/claude-essential-plugin