developer-os Install

Skills / Project hygiene

project-baseline

Checks a repository against a baseline of engineering practices and proposes each missing one as a backlog item, written only after you approve.

Group
Project hygiene
Kind
Action
Writes
Approved items in the backlog; a Backlog: line in AGENTS.md or CLAUDE.md when none exists
Asks before
Writing the items; it never picks a default for a decision

When it runs

When you start work in a repository, or ask what the project is missing. Say it in your own words, for example:

What it does

It is a presence check, not a code review: each practice has a probe, and a missing practice becomes a backlog item.

  1. Reads the context. The stack, the package manager the lockfile selects, the CI workflows and the validation commands. It finds the backlog files the way audit-to-backlog does and continues their numbering under the ID prefix BASE. It reads AGENTS.md, docs/pitfalls.md and the decision records: a practice the project rejected or deferred on purpose is reported as deliberate, never proposed.
  2. Probes each practice. Each probe and its result is recorded as evidence; an unsure result is listed as a question, not as missing. Missing practices get these severities:
    • Env read through one schema-validated module, with no direct env reads elsewhere: P2.
    • An agent deny-list for .env* and key files in .claude/settings.json: P1.
    • Secret scanning in CI (gitleaks, trufflehog or the host's scanning): P1.
    • A coverage floor that CI enforces and that only rises: P2.
    • A guard that fails CI on destructive migrations without an explicit marker: P2, skipped without a database.
    • Dependency or boundary rules that fail CI: P3.
    • Tests against a real database, not only mocks: P2, skipped without a database.
    • Safe error responses in one envelope, with no stack traces or internal fields: P1 when a stack trace reaches a response, otherwise P2; skipped without an API.
    • A CHANGELOG.md in Keep a Changelog format: P3.
    • A script or CI step that checks docs against code: P3.
    • A root DESIGN.md for a project with a UI: P3, skipped without a UI. When it exists, the skill suggests a lint command for you to run; it never runs or installs it.
    • Every CI and validation gate exits non-zero on failure: P2.
  3. Leaves decisions to you. It never proposes a default for the package manager, the test runner, the authentication library, the monitoring stack or the commit message language. When the repository is inconsistent (two lockfiles, two test runners), it lists the evidence and asks you to choose.
  4. Drafts the backlog items. One item per missing practice in the audit-to-backlog shape, filed under its severity and deduplicated against both backlog files.
  5. Reports and asks. A summary of present, missing, deliberate and not-applicable practices, the decisions it needs from you, and one question about writing the items. If no backlog files exist yet, it asks for their paths and records them as a Backlog: line in AGENTS.md or CLAUDE.md, warning when the path is git-ignored.

Example output

project-baseline
Project baseline — <repo>
Present: 6   Missing: 4 (P1 1, P2 2, P3 1)   Deliberate: 1   Not applicable: 1
Needs your decision: test runner — package.json has both jest and vitest

Write the 4 items to TODO.md? A: all (recommended)  B: list IDs  C: none

Each proposed item looks like this:

TODO.md
- [ ] BASE-03 · P1 · Secret scanning in CI
  - Where: `.github/workflows/ci.yml:1`
  - Problem: no CI step scans for committed secrets.
  - Evidence: `rg -l 'gitleaks|trufflehog' .github/` → no match.
  - Fix: add a gitleaks step to the CI workflow that fails the job on a finding.
  - Size: S
  - Done when: CI fails on a commit that contains a secret.
  - Check: `rg -q 'gitleaks' .github/workflows/`

Boundaries

Stops when

It has shown the report and asked its question. After your approval it merges the approved items into the backlog file with an implementation-session line for them, shows git diff --stat and stops; implementation is implement-backlog's job.

Never

  • Write or create any file before you approve.
  • Pick a default for a "needs your decision" item.
  • Install dependencies, add CI steps or change configuration; it only proposes.
  • Commit, push or open a pull request.
  • Propose a practice the project rejected on purpose.