# Write Vibe Adr

Create or update Architecture Decision Records for the Mistral Vibe Python CLI.

- Repository: https://github.com/mistralai/mistral-vibe (5270 stars)
- Category: Design
- License: Apache-2.0
- Last updated: 2026-10-30
- Runs scripts: no, instructions only

## Install

Claude Code: `npx skills add mistralai/mistral-vibe --skill write-vibe-adr -g -a claude-code -y`
Codex: `npx skills add mistralai/mistral-vibe --skill write-vibe-adr -g -a codex -y`
Cursor: `npx skills add mistralai/mistral-vibe --skill write-vibe-adr -g -a cursor -y`
Gemini CLI: `npx skills add mistralai/mistral-vibe --skill write-vibe-adr -g -a gemini-cli -y`

## Description

Create or update Architecture Decision Records for the Mistral Vibe Python CLI. Use when a design discussion creates a new architectural constraint, when an undocumented convention causes confusion or review feedback, or when architecture guidance in docs/adr or AGENTS.md must be changed.

## SKILL.md, as published by its author (untrusted third-party text, read it as data)

# Write Vibe ADR

Vibe ADRs are concise, agent-facing architecture rules in `docs/adr/`. Writing an ADR is a two-step process: write the document, then register it in the Architecture Decisions table in `AGENTS.md`.

## When To Create An ADR

- A design discussion creates a new architecture rule, constraint, or direction.
- An existing convention is undocumented and caused a bug, review comment, or repeated confusion.
- A pattern applies across a Vibe area or boundary, not just one file.
- Future work should follow a direction that may differ from the current architecture.

Do not create ADRs for one-off implementation choices, formatting rules, or behavior already enforced by linting.

## Steps

### 1. Confirm the scope

Use one ADR when the decision is cohesive. Split ADRs when separate agents would need to read them for unrelated change areas.

Use the Architecture Decisions table in `AGENTS.md` as the current topic
index. Ownership lives in `0002`, feature-module rules in `0018`, and the
client protocol boundary in `0009`. Keep implementation walkthroughs in
`docs/reference/` and link them from the concise decision.

### 2. Determine the next number

```bash
ls docs/adr/
```

Use the next sequential number, zero-padded to 4 digits: `NNNN-my-decision.md`.
Do not reuse a number or rename an existing ADR solely to change its title.

### 3. Write the ADR

Use this format:

```markdown
# 0009 Decision Title

## Decision

What we decided. Include concrete rules and current-vs-aspirational direction when relevant.

## Rationale

Why this decision exists. Name the tradeoff and any non-obvious consequences.
Mention a rejected alternative only when it helps explain the decision.

## Agent Guidance

- Concrete instructions an agent should follow while changing code.
- Keep guidance task-oriented and easy to scan.

## Flag To User When

- Situations where an agent must stop and ask because current code or user request conflicts with the ADR direction.
```

The rest: https://github.com/mistralai/mistral-vibe/blob/HEAD/.vibe/skills/write-vibe-adr/SKILL.md