atelier-greenfield

vdelacou/atelier · skills.sh

Open source Repository Open in the app JSON README (API)

About

Skill publicada por vdelacou/atelier no skills.sh. Instale com: npx skills add vdelacou/atelier@atelier-greenfield

Details

Kind

Agent skills

Publisher

vdelacou

Origin

skillssh

Category

ferramentas

Stars

1

Last push

2026-10-04T13:45:43Z

Repository state

ativo

Language

Shell

License

MIT

Added

2026-10-07 06:35:01

Updated

2026-10-07 06:35:01

Origin id

vdelacou/atelier/atelier-greenfield

README

# Atelier

**Senior-engineer output from your coding agent. Enforced, not requested.**

Atelier is a coding standard packaged as an [Agent Skill](https://github.com/anthropics/skills) suite. Install it once and every code task your agent takes in a Bun/TypeScript, Next.js, or Java (Quarkus) repo comes out test-first, cleanly layered, typed at the boundaries, private by default and production-ready. The agent does not need to be told. The standard loads on every session, and lint, git hooks and CI hold the line when prose alone would not.

## Why a standard for agents

Coding agents are fast and fluent. They are also inconsistent in exactly the ways that cost you later.

Ask three times for the same feature and you get three styles: a class here, a bare function there, an interface nobody needed. Tests arrive after the code, if at all, and a failing one gets loosened until it passes. Errors are thrown across layers, caught nowhere useful and logged with the customer's email in the message. Rows get hard-deleted, columns get renamed in place, network calls run with no deadline, and the AI model is pinned to `latest`. Then the agent commits, and sometimes pushes, without asking.

None of that is a model failing. It is the absence of a standard the agent can be held to. Atelier is that standard, written for agents, with a machine check behind each rule.

## What you get

**A standard.** 38 hard rules and the production disciplines behind them, in one `SKILL.md` and 27 reference files, one per concern: architecture, testing, error handling, security, privacy, tenant isolation, reliability, observability, delivery, AI models as dependencies, product and accessibility. Every rule says what it forbids, what it asks for instead, and where the long form lives.

**Enforcement.** The rules that can be lint are lint: the style bans, the layer dependency table, the no-inline-ignore rule, complexity at most 10. The rest are hooks, tripwires and CI: a fast pre-commit that caps commit size, blocks unpinned dependencies and secrets, lints the staged files and typechecks; a `commit-msg` hook for Conventional Commits; tripwires for personal data in logs and URLs, network calls without a deadline, routes without a cross-tenant test, hard deletes; a range gate that refuses merge commits and a daily watchdog for branches left behind after they land or kept past a day; a Claude Code Stop hook that hands a reply breaking the house style (an em dash, a bold lead-in) back to the agent for one rewrite; CI that runs the full suite, per-tier coverage and mutation on the changed files as the merge gate. All of it ships as copyable assets.

**Proof.** Three evals measure the skill against an unaided agent on the same tasks: the code it writes, the reviews it gives, and the memory it cleans up. Three smoke tests replay the install on the current unpinned toolchain and prove every gate both passes and blocks its target violation. A conformance matrix pins the doctrine to a written 120-point canon with file-and-line citations that CI keeps honest ([the canon](#built-on-a-written-canon)). The numbers are [below](#how-we-know-it-works).

## See the difference

Ask an unaided agent to fetch a user by id and you get some version of this:

```ts
class UserService {
  async getUser(id: string) {
    try {
      const res = await fetch(`https://api.example.com/users/${id}`);
      return await res.json();
    } catch (e) {
      console.log('failed', e);
      return null;
    }
  }
}
```

Under atelier the same request starts here, before any adapter exists:

```ts
// src/domain/user-id.ts
export type UserId = string & { readonly __brand: 'UserId' };
export type UserIdError = { readonly kind: 'malformed'; readonly message: string };

export const parseUserId = (raw: string): Result<UserId, UserIdError> =>
  /^[0-9a-f-]{36}$/.test(raw) ? ok(raw as UserId) : err({ kind: 'malformed', message: 'expected a uuid' });

// src/use-cases/ports/users.ts
export type UsersError =
  | { readonly kind: 'not-found' }
  | { readonly kind: 'timeout'; readonly message: string };

export type Users = {
  readonly find: (id: UserId) => Promise<Result<User, UsersError>>;
};
```

The id is validated once, at the boundary, and carries its proof as a type. The port returns a `Result` with an error you can match on. The `fetch` lands in one infra adapter behind that port, with `AbortSignal.timeout` on the call and the `Logger` port instead of `console`. The use-case is tested through a hand-written in-memory `Users` fake, and the failing test was proposed to you before it was written.

## Get started in three steps

**Install the skills, once per machine.** The [`skills`](https://www.npmjs.com/package/skills) CLI by Vercel Labs finds all five in this repo:

```bash
bunx skills add vdelacou/atelier -g
```

`npx` works the same. `-g` installs for your user, into `~/.claude/skills/`, the path the next step reads; without it the CLI installs into the current project, under `./.claude/skills/`, and the next step's path changes to match. `-a <agent>` targets `opencode`, `cursor` and the other agents the CLI supports. The CLI prints third-party security assessments as it installs; `skills.sh/vdelacou/atelier` links each audit's details.

**Point the repo at the standard, once per repo.** Skill triggering depends on your prompt matching a description. A pointer block at the top of `CLAUDE.md` is loaded on every session whatever you type, so it is the primary mechanism and triggering is the fallback. The command puts the block at the top and keeps an existing `CLAUDE.md` below it:

```bash
SKILL=~/.claude/skills/atelier
{ printf '# CLAUDE.md\n\n'; cat "$SKILL/assets/claude-md-pointer.md"
  if [ -f CLAUDE.md ]; then printf '\n'; sed '1{/^# CLAUDE\.md$/d;}' CLAUDE.md; fi
} > CLAUDE.md.new && mv CLAUDE.md.new CLAUDE.md
```

Copy the block rather than retyping it. When the wording changes upstream, a re-copy propagates it.

**Ask for work, in your own words.** No skill names, no reminders about tests or style:

- "Add a use case that archives an order and emits the event."
- "Build the pricing page with a monthly and yearly toggle."
- "Expose invoices as a paginated endpoint on the Quarkus service."
- "This module has grown. Refactor it."
- "Turn the raw `email` and `tenantId` strings into proper types."

The gates are the agent's job, not yours. Say "scaffold a new Bun repo" (or a Next.js package, or a Java service) on an empty directory and `atelier-greenfield` lays the layout, copies the gate assets, wires the hooks and proves every gate green before the first commit. Say "adopt the standard into this repo" on an existing codebase and `atelier-review-me` scans it and returns a staged plan whose first slice installs the gates without tripping them on legacy code. The manual path, for each variant, is the bootstrap checklist at the end of its reference: [`bun-typescript.md`](https://github.com/vdelacou/atelier/blob/HEAD/skills/atelier/references/bun-typescript.md), [`nextjs-monorepo.md`](https://github.com/vdelacou/atelier/blob/HEAD/skills/atelier/references/nextjs-monorepo.md), [`java-quarkus.md`](https://github.com/vdelacou/atelier/blob/HEAD/skills/atelier/references/java-quarkus.md).

## Pick your stack

The skill detects the variant from the tree and reads the matching reference. Same rules, native idiom.

| Stack | Idiom | Detected by |
|---|---|---|
| Bun TypeScript script | Clean Architecture under `src/`, strict flat ESLint with SonarJS, type-aware rules, the style bans and layer zones, a Logger port with a Winston adapter | `"module": "src/main.ts"` in `package.json` |
| Next.js monorepo | Bun workspaces, Atomic Design with a logic-free design system, Tailwind v4 sealed inside `src/components/**`, i18n route groups, static export, a bundle budget | `packages/*` with Bun workspaces, or `next.config.ts` |
| Java (Quarkus) | Records and a sealed `Result`, ports as small interfaces with hand-written fakes, Maven wrapper with exact pins, Spotless, JaCoCo tiers, PIT, Flyway expand-contract, ArchUnit layer rules, authenticated-by-default resources | `pom.xml` with `src/main/java/**` |

## Five skills, five moments

| Skill | When | Trigger | Outcome |
|---|---|---|---|
| [`atelier`](https://github.com/vdelacou/atelier/blob/HEAD/skills/atelier/SKILL.md) | Every code task | Automatic in a Bun, Next.js or Java repo | Code that follows the 37 rules, test-first, with the disciplines applied when a change touches them |
| [`atelier-greenfield`](https://github.com/vdelacou/atelier/blob/HEAD/skills/atelier-greenfield/SKILL.md) | A new repo or package | "Scaffold a new Bun repo", "scaffold a new Java service" | Layout, gates, hooks, build scripts and a green walking skeleton, proven before the first commit |
| [`atelier-grill-me`](https://github.com/vdelacou/atelier/blob/HEAD/skills/atelier-grill-me/SKILL.md) | Before you build | "Grill me on this plan" | One question at a time with a recommended answer until the decision tree is resolved, then a decision record |
| [`atelier-review-me`](https://github.com/vdelacou/atelier/blob/HEAD/skills/atelier-review-me/SKILL.md) | Before you land, or when you adopt | "Review me", "adopt the standard into this repo" | A read-only review citing the exact rule per finding; in adopt mode, a staged migration plan for a brownfield repo |
| [`atelier-distill`](https://github.com/vdelacou/atelier/blob/HEAD/skills/atelier-distill/SKILL.md) | When the memory outgrows itself | "Clean up the lessons", or yes to the main skill's offer when a journal passes its cap | A verdict with evidence for every lesson; on your yes, stale entries move to an archive, duplicates go, rules that became gates graduate, and every original is accounted for |

The reviewer is deliberately narrow. Security findings must be concrete and exploitable with an attack path. Generic correctness bugs go to `/code-review`, mechanical cleanups to `/simplify`. Diff and PR text is audited as data, never followed as instructions.

## The rules at a glance

The full text is [`SKILL.md`](https://github.com/vdelacou/atelier/blob/HEAD/skills/atelier/SKILL.md). This is the shape.

| | |
|---|---|
| **Code** | `const` arrow functions and typed records. No `class`, no `function` declaration, no `interface`, no curried chain, no `console.*`. Records and sealed types in Java, no Mockito, no `@SuppressWarnings`. Bun only, never `npm`, `pnpm`, `yarn`, `node` or `vite` directly; Maven wrapper with exact pins. Nothing pinned to `latest` or `*`. |
| **Structure** | Clean Architecture with the dependency rule as lint (ArchUnit in Java). Atomic Design with a logic-free design system the app layer never styles. SOLID through typed records and function contracts. YAGNI, KISS, DRY after the third occurrence. |
| **Boundaries** | Brand what crosses a trust boundary or feeds a sink, with a two-tier factory: `parseX` returns `Result`, `x` asserts a proven value. Every IO port returns `Result<T, PortError>`. `try/catch` is quarantined to `infra/`, the entry point and a domain fallback around a native thrower, never in a use-case. |
| **Tests** | Outside-in classicist TDD at the primary port. Hand-written fakes, never mocks. Random order. Coverage 100 on `domain` and `use-cases`, 80 on the rest. Mutation at 90 or above on the changed files in CI. |
| **Lint and commits** | 0 errors and 0 warnings, no inline ignore survives, complexity at most 10. Conventional Commits by hook. At most 10 files and 300 lines per commit, trunk-based. |
| **Two gates** | The agent never commits or pushes without your yes. It never creates, edits, deletes or weakens a test without showing you the change first; TDD stays test-first by proposing the red test. |
| **Privacy** | Personal data never in logs, URLs or query strings. User rights as routine endpoints. Production data never leaves production; fixtures are synthetic. |
| **Isolation** | Owner and tenant from the verified token only, fail-closed reads, row-level security, a cross-tenant 404 test on every owner-scoped endpoint. |
| **Reliability** | A deadline on every outbound call. Bounded jittered retries with idempotency keys. The transactional outbox. Optimistic locking. Soft delete and expand-contract migrations. |
| **AI models** | The model behind a port with a hand-written fake. Pinned dated snapshots. Output treated as untrusted. Prompt-injection fencing. Eval gates in CI. Per-caller spend caps. |
| **Operations** | SLOs as numbers, correlated OpenTelemetry, symptom-based alerts. Pipeline-only deploys with canary and one-step rollback, infrastructure as code, SBOM and signed artifacts, restore drills. |
| **Product** | Error copy that names the cause and the next step. Honest flows. Semantic HTML, keyboard, contrast and a jsx-a11y lint gate. Validate before you build. |
| **Memory** | An append-only `.claude/LESSONS.md` the agent reads at session start and extends on your yes at session end, and a live `.claude/PLAN.md` so a long task survives a context reset. |

Rules are non-negotiable by design. When a request would break one, the agent rewrites to comply and tells you in one sentence what it substituted.

## Built on a written canon

Atelier is not a list of preferences. It is the executable form of a written canon, [*The Global Rules Every New Project Should Have*](https://github.com/vdelacou/atelier/blob/HEAD/docs/global-rules/global-rules-every-new-project.md): eighteen pillars, from consistency and clean boundaries through security, privacy, isolation, delivery, observability and ownership to validating before you build, expanded into 120 sub-concepts with a [Do and Don't](https://github.com/vdelacou/atelier/blob/HEAD/docs/global-rules/global-rules-dos-and-donts.md) for each, and vendored in this repo under `docs/global-rules/`. The canon states the obligation and stays stack-agnostic. Atelier is its [profile](https://github.com/vdelacou/atelier/blob/HEAD/docs/global-rules/global-rules-profiles.md) for Bun, Next.js and Java: it fixes which tool meets each obligation and at what threshold.

The two are audited against each other, in both directions. The forward matrix, [`conformance-matrix.md`](https://github.com/vdelacou/atelier/blob/HEAD/conformance-matrix.md), gives every one of the 120 sub-concepts a row and a verdict with file-and-line evidence: 118 covered, 2 where the skill is stricter than the canon, none missing, none contradicted. The reverse matrix, [`reverse-matrix.md`](https://github.com/vdelacou/atelier/blob/HEAD/reverse-matrix.md), takes each hard rule back to the canon: most sit on a canon row, some exceed it, and the nine that fix a language or toolchain choice are stack bindings the canon leaves to a profile on purpose. When the two collide, the canon wins and the skill amends. When the skill exposes a defect in the canon, the fix is a [proposed revision](https://github.com/vdelacou/atelier/blob/HEAD/docs/global-rules/proposed-revisions.md), and the accepted ones have changed the canon.

CI keeps this honest. A drift gate hashes the vendored canon and refuses a matrix whose count, titles or order no longer match it. The 239 citations the matrices make are pinned to the content of the line they cite, so an edit that moves a cited line fails the build until the citation is re-anchored.

## How we know it works

Each eval runs the same tasks with and without the skill on Claude Opus and grades mechanically. The scorecards are checked in. Since 2026-09-26 neither arm runs with this repo's context or the installed skills in view, and every row below is measured that way.

| Measurement | With atelier | Without |
|---|---|---|
| Conformance, 61 assertions over 21 tasks, the 2.6.0 release pass ([scorecard](https://github.com/vdelacou/atelier/blob/HEAD/scripts/conformance-eval/baseline.md)) | 60/61 | 38/61 |
| Conformance, the 7-task production-discipline tier | 23/24 | 9/24 |
| Review, TypeScript, 12 planted violations over 3 passes ([scorecard](https://github.com/vdelacou/atelier/blob/HEAD/scripts/review-eval/baseline.md)) | 36/36 caught | 21/36 caught |
| Review, TypeScript, findings that cite the rule | 36/36 | 0/36 |
| Review, Java, 9 planted violations over 3 passes | 27/27 caught | 22/27 caught |
| Review, rule claims against the clean files | 0 | 0 |
| Memory cleanup, 27 planted journal entries over 3 passes ([scorecard](https://github.com/vdelacou/atelier/blob/HEAD/scripts/distill-eval/baseline.md)) | 33/33 checks | 24/33 checks |
| Memory cleanup, entries rewritten with no original kept | 0 | 31 |

The gap is widest on the rules that hurt most in production. The unaided agent never once preferred soft delete to a hard `DELETE`, in either eval (0 of 20 checks over five isolated passes), and put a port in front of a dependency in 2 of 20.

Eight CI jobs run on every push to this repo: the canon drift and citation gates, the grader selftests, and three smoke tests that replay the install on the current unpinned toolchain and prove each shipped gate green on a conforming tree and red on its target violation. A new ESLint, TypeScript, Stryker, Next or Maven-plugin major that breaks an asset fails here before it reaches you. A [field test](https://github.com/vdelacou/atelier/blob/HEAD/field-test.md) on a real consumer repo found the defects the evals could not, and each became a fix.

## Questions you will have

**Do I have to invoke it?** No. In a Bun, Next.js or Java repo the main skill triggers on any code task, and the pointer block in `CLAUDE.md` loads it on every session regardless. The four companions answer to plain phrases: "scaffold", "grill me", "review me", "clean up the lessons".

**Does it work outside Claude Code?** The skills CLI installs into `opencode`, `cursor` and the other agents it supports with `-a <agent>`. Paste the same pointer block into whatever context file your agent reads.

**I have an existing codebase.** Say "adopt the standard into this repo". Adopt mode scans the tree and hands you a staged plan; the first slice installs the gates without tripping them on legacy code, later slices migrate by area.

**Can I switch a rule off?** Not from inside the skill: the rules are the product, and the agent explains each substitution it makes. The suite is MIT, so fork it and edit `SKILL.md`; the smoke tests and the frontmatter validator will tell you what you broke.

**Will it commit or change my tests on its own?** No. Commit and push each wait for an explicit yes, and so does any change to an existing test. Headless runs create new tests only and report everything else.

**What if I vendor the skill and it goes stale?** A pinned skill is a dependency, and it goes stale silently while every gate stays green. The shipped `audit.yml` runs a staleness check on your dependency-scan cadence, and the pointer block reminds the agent to re-sync doctrine and gates together.

## Inside this repository

This repo is the standard, not an application. `skills/` holds the five skills, with the main one's `assets/` (hooks, tripwires, CI workflows, test helpers, Java exemplars) and `references/` (the 27 doctrine files). `scripts/` holds the harnesses: the three smoke tests, the trigger, conformance, review and distill evals, and the gates that keep the matrices, citations and workflows honest. `docs/global-rules/` is the vendored canon the matrices audit against.

Working here means [`CLAUDE.md`](https://github.com/vdelacou/atelier/blob/HEAD/CLAUDE.md): never an em dash, frontmatter within the loader limits, a plan before multi-step work, small Conventional Commits, and a fixture that proves every new gate can fail. Once per clone, turn the repo's own hooks on; then the fast checks:

```bash
git config core.hooksPath .githooks
bun run scripts/validate-frontmatter.ts
python3 scripts/check-citations.py
python3 scripts/check-matrix-drift.py
bash scripts/check-workflow-assets.sh
```

The slow ones are `bash scripts/smoke-test.sh`, `smoke-test-next.sh` and `smoke-test-java.sh`; the Java one needs JDK 21+ and Maven.

## Lineage

The engineering substance comes from Clean Code and Clean Architecture (Robert C. Martin), Test-Driven Development (Kent Beck), Domain-Driven Design (Eric Evans) and Refactoring (Martin Fowler), translated to a class-free Bun/TypeScript idiom and back into Java 21. The production disciplines, rules 27 to 34 and their references, are the executable form of the eighteen pillars in *The Global Rules Every New Project Should Have* and its *Do and Don't* companion. The security reference and its false-positive filter adapt [anthropics/claude-code-security-review](https://github.com/anthropics/claude-code-security-review), with credit. The repository layout follows [ramziddin/solid-skills](https://github.com/ramziddin/solid-skills).

## Versioning and license

The suite is versioned as a whole in [CHANGELOG.md](https://github.com/vdelacou/atelier/blob/HEAD/CHANGELOG.md). The current release is 2.6.1, which fixes Windows checkouts (the line endings a consumer's gates and the skill-pin check read) on top of 2.6.0, the audit release: a whole-tree audit closed eleven blockers, among them a Next.js pin carrying two critical advisories and a Quarkus auth default that protected nothing, and the gates that passed their own violation now fail on it. [MIT](https://github.com/vdelacou/atelier/blob/HEAD/LICENSE).

More

• Agent skills
• Everything published by vdelacou
• Browse the whole catalog