# Standards

> Scans the repository and writes docs/standards.md with its real conventions, each backed by evidence. Use when starting level-2/3 work without that file, or when conventions changed.

- Skill: `jeffersonvalente/standards` (Agent Skill)
- Install (CLI): `npx get-skill add jeffersonvalente/standards`
- Raw SKILL.md: https://api.skillmd.com/api/skills/jeffersonvalente/standards/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: jeffersonvalente (https://skillmd.com/u/jeffersonvalente)
- Updated: 2026-11-19
- Page: https://skillmd.com/skills/jeffersonvalente/standards

---


# /cardume-core:standards — Capture the project's conventions

You run without the conversation history; everything you need is in the repository.

Goal: a short, evidence-backed `docs/standards.md` that tells any agent how *this* project is
written, so its output fits in without re-discovering conventions every session.

## 1. Gather evidence

Read, don't guess:
- Manifests and tooling: `package.json`, `pyproject.toml`, `pom.xml`, `go.mod`, lockfiles,
  linter/formatter configs (`.eslintrc*`, `ruff.toml`, `.prettierrc`, `.editorconfig`), `tsconfig.json`.
- Layout: top-level directories and where source, tests, scripts and config live.
- Code samples: 5–10 representative files across layers (entry points, a service/module, a model,
  an API handler or component, a test). Note naming (files, functions, classes), error handling,
  logging, configuration/env access, dependency injection, async style.
- Tests: framework, location and naming, fixtures/mocks style, how they are run.
- History and delivery: `git log --oneline -30` (commit message style), branch names
  (`git branch -r | head`), CI workflows, PR templates.
- Existing docs: README, CONTRIBUTING, ADRs, `CLAUDE.md`, `AGENTS.md`.

## 2. Write `docs/standards.md`

Keep it under ~150 lines. Every rule is something an agent can follow, and cites evidence:

```markdown
# Project standards

Generated by /cardume-core:standards on <YYYY-MM-DD>. Sections marked "(manual)" are kept on regeneration.

## Principles (manual)
<!-- Normative rules the team commits to (e.g. "every money amount is integer cents",
"no PII in logs"). Written or approved by the user; never rewritten by this skill. -->
- ...

## Stack
- TypeScript 5 + Node 22, Fastify (package.json); Postgres via Prisma (prisma/schema.prisma)

## Layout
- Source in src/<domain>/, tests next to code as *.test.ts (src/billing/invoice.test.ts)

## Conventions
- Errors: throw AppError subclasses, never raw Error (src/errors.ts, 14 usages)
- ...

## Tests
- Vitest; run with `pnpm test`; one describe per module ...

## Delivery
- Conventional Commits (git log); branches feat/<ticket>-<slug> ...

## Inconsistencies seen
- Two date libraries in use (dayjs in src/billing, date-fns in src/reports) — prefer: ask the team
```

Rules:
- Describe what the code does today, not what you would prefer. Where the code is inconsistent,
  list it under "Inconsistencies seen" instead of picking a winner.
- No generic advice ("write clean code"); only project-specific facts.
- If `docs/standards.md` already exists, update it: keep any section whose heading ends in
  "(manual)" exactly as written, refresh the rest.
- `## Principles (manual)` is normative and belongs to the user: `spec` and `gate` check work against
  it. Never fill it with conventions you observed or rewrite it; on first creation leave the
  placeholder and, if the code suggests candidates, list them in your summary for the user to adopt.
  Everything else in the file is descriptive (what the code does today).

## 3. Return

A short summary: the file path, the 5 most important conventions found, the inconsistencies the
team should decide on, and any candidate principles for the user to add to `## Principles (manual)`.

