# Karvey Standards

> Karvey Standards (engineering golden-paths uplift)

- Skill: `mauricioquezadahaintech/karvey-standards` (Agent Skill)
- Install (CLI): `npx skillmds@latest add mauricioquezadahaintech/karvey-standards`
- Raw SKILL.md: https://api.skillmd.com/api/skills/mauricioquezadahaintech/karvey-standards/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: MauricioQuezadaHaintech (https://skillmd.com/u/mauricioquezadahaintech)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/mauricioquezadahaintech/karvey-standards

---


# Karvey Standards (engineering golden-paths uplift)

## Purpose

Populate and maintain the **engineering standards** (`standards/{layer}.md`) by reading the team's
**real codebase**, not by inventing them. This is the skill the public method ships so that each team
that installs Karvey can **lift its own standards** into the structure defined by
`karvey/rules/engineering-standards.md`, and keep them fresh over time.

> **Two planes — read this first.** The Karvey **method** (this plugin) is generic and public; it MUST
> NOT contain any team's concrete standards. The **standards themselves** are the team's data and live in
> the team's **own standards repo** (e.g. a private Azure DevOps repo), resolved via
> `project.json:standards`. This skill **writes to that standards repo, never into the plugin**.

## When to use

- **Bootstrap** (`--bootstrap`): first time — there are no standards yet, distill them from the system.
- **Refresh** (`--refresh`): standards exist but drifted, or recurring `deviations.md` entries should become
  the new norm (see `engineering-standards.md` feedback loop), or a migration advanced (e.g. frontend v2→v3).

## Execution steps

### Step 1 — Resolve the standards target

Read `docs/spec/project.json` → `standards` (`source`, `dir`/`repo`, `path`, `by_layer`) and `repos`, `targets`.
Resolve **where standards live and will be written**:
- `source: "local"` → the folder `standards.dir` inside the `spec_repo`.
- `source: "git"` → the external standards repo (`standards.repo`, `ref`, `path`). Ensure a working copy
  exists (shallow clone/pull into a cache, e.g. `.karvey/standards/`), and work there. This is the private
  org repo (e.g. Azure DevOps).

If `standards` is not configured, ask the user where standards should live (local vs git repo) and write it
back to `project.json` per `rules/project-config.md`. **Never** target the public plugin repo.

### Step 2 — Decide scope (which layers/targets)

From the argument `<layer>` if given, else from `project.json:targets` and the repos' nature, decide which
standards to lift: typically `db`, `backend`, `frontend` (+ `infra`, mobile/CLI per `targets`).

### Step 3 — Discovery per layer (read the real system)

For each layer, dispatch **parallel subagents** (Explore) over the relevant `project.json:repos` to extract,
with concrete `file:line` evidence:
- The **golden path**: the canonical, real pattern (naming, structure, layering) + a copyable reference example.
- **MUST** (hard rules already enforced de facto) and **MUST NOT** (anti-patterns visible in the code).
- **Divergences** between repos (where the same thing is done in several ways → a standard must pick one).
- **Migration state** if applicable (e.g. a `current`/v2 pattern being replaced by a `target`/v3 one).
- **Gaps**: things genuinely undefined.

Also read each repo's `CLAUDE.md` / `CONTRIBUTING.md` / `README.md` / steering docs and fold in tribal rules.

### Step 4 — Draft each `standards/{layer}.md`

Follow the **fixed template** in `karvey/rules/engineering-standards.md` exactly:
`Status` · `Applies to targets`/`Repos` · `Source of truth` · `Golden path` (with real example) · `MUST` ·
`MUST NOT` · `Gray zones` (decisions that must trigger design-mode questions) · `Migration` (if `migrating`).

Rules while drafting:
- Distill from evidence; **cite the `Source of truth`** files. Do not idealize.
- Where a divergence exists, pick the **recommended** golden path and record the others as `MUST NOT` or as a
  gray zone, with a one-line rationale.
- Anything undefined → a `> TODO` placeholder **and** a gray zone (so it surfaces as a design-mode question the
  first time it's hit, instead of being silently guessed).
- Migrations → `Status: migrating`, with `current` (deprecated) and `target` (mandatory for new work).

### Step 5 — Human review gate (standards are policy)

Present each drafted standard's summary (golden path + MUST/MUST NOT + gray zones + open TODOs) and get
approval. Standards govern every future change, so they are not auto-adopted.
- With `-y`: auto-approve (use only when re-running a previously approved draft).
- Otherwise: use `AskUserQuestion` per layer (adopt as-is / adjust / skip).

### Step 6 — Write to the standards repo + index

In the resolved standards working copy (Step 1):
- Write/update each `standards/{layer}.md`.
- Update `standards/_index.md`: layer → file, maturity (`draft`/`active`), `applies-to` targets/repos, last-uplift date.
- Update `project.json:standards.by_layer` if files were added.
- **Git**: if the standards repo is versioned, work on a feature branch (respect `rules/deploy-workflow.md`),
  commit with human + AI traceability (`rules/changelog-policy.md`). **Do not push without the user's OK.**
- **Never** write any of this into the public plugin repo.

### Step 7 — Output

```
✅ Standards uplift complete ({bootstrap|refresh})

Standards repo: {local dir | git repo}
Layers: {db, backend, frontend, ...}
  db.md       — active   (source: {ref})
  backend.md  — draft    ({N} divergences flagged as gray zones)
  frontend.md — migrating (current: v2 / target: v3)
Open TODOs / gray zones: {N}  → will surface as design-mode questions in architecture/impl

Next: architecture and impl will load these as a hard constraint (conformance gate).
Refresh anytime with: /karvey-standards --refresh
```

## Relationship with the rest of the method

- **Feeds** `karvey-architecture` (Step 4B gate) and `karvey-impl` (Step 4) — they read what this skill writes.
- **Closes the loop** with `deviations.md`: at `--refresh`, review recurring deviations and promote the ones
  that should become the new norm into the standard (see `engineering-standards.md`).
- **Not a pipeline phase**: it does not advance `spec.json:phase` (see `rules/support-skills.md`).
- `karvey-init` may invoke this on first project setup to bootstrap standards for the declared `targets`.

---
*Part of the Karvey™ Method — © HainTech, by Mauricio Quezada Ibáñez · Apache 2.0 · see `karvey/LICENSE` and `karvey/TRADEMARK.md`.*