@g3nomaly/g3n-skills 0.0.0-stage → 0.1.1

package/.claude-plugin/marketplace.json

@@ -0,0 +1,92 @@
+{
+  "name": "g3n",
+  "owner": {
+    "name": "g3ntrovert"
+  },
+  "plugins": [
+    {
+      "name": "agent",
+      "source": "./skills/agent",
+      "description": "Rules every agent session follows: the session bootstrap, its boundaries, and working in worktrees.",
+      "skills": [
+        "./bootstrap",
+        "./worktrees"
+      ]
+    },
+    {
+      "name": "coding",
+      "source": "./skills/coding",
+      "description": "How to write, check and document code, per language, and query a repository with analyze.",
+      "skills": [
+        "./code",
+        "./document",
+        "./analyze"
+      ]
+    },
+    {
+      "name": "grilling",
+      "source": "./skills/grilling",
+      "description": "Relentless interviews that stress-test a plan, plus the domain model they feed.",
+      "skills": [
+        "./grilling",
+        "./grill-me",
+        "./grill-with-docs",
+        "./domain-modeling"
+      ]
+    },
+    {
+      "name": "speech",
+      "source": "./skills/speech",
+      "description": "Conventions for how an agent writes — emphasis markup and cutting AI tells.",
+      "skills": [
+        "./emphasise",
+        "./unslop"
+      ]
+    },
+    {
+      "name": "task-manager",
+      "source": "./skills/task-manager",
+      "description": "Query and drive a tree of plans, phases and tasks through hooks, with the plan's decisions and the project vocabulary kept beside them.",
+      "skills": [
+        "./task-manager",
+        "./vocabulary",
+        "./decisions"
+      ]
+    },
+    {
+      "name": "using-hooks",
+      "source": "./skills/using-hooks",
+      "description": "How to write each Claude Code lifecycle hook.",
+      "skills": [
+        "./hook-pre-tool-use",
+        "./hook-post-tool-use",
+        "./hook-stop",
+        "./hook-user-prompt-submit"
+      ]
+    },
+    {
+      "name": "workflow",
+      "source": "./skills/workflow",
+      "description": "Work a phase of a plan through plan, execute, review and sync, one agent per step, with hooks deciding when a step is finished.",
+      "skills": [
+        "./run",
+        "./plan",
+        "./execute",
+        "./review",
+        "./sync",
+        "./orchestrator",
+        "./worktree"
+      ]
+    },
+    {
+      "name": "writing",
+      "source": "./skills/writing",
+      "description": "How to write skills, hooks and tasks that an agent can follow.",
+      "skills": [
+        "./writing-great-hooks",
+        "./writing-great-skills",
+        "./writing-great-tasks"
+      ]
+    }
+  ]
+}

package/package.json

@@ -1,6 +1,27 @@
 {
   "name": "@g3nomaly/g3n-skills",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.1",
+  "description": "The g3n skills, each with its own hooks: a skill source for @g3nomaly/skills and a Claude Code plugin marketplace.",
+  "type": "module",
+  "files": [
+    ".claude-plugin",
+    "skills"
+  ],
+  "scripts": {
+    "build": "bun run build:marketplace",
+    "build:marketplace": "bun scripts/build-marketplace.ts",
+    "typecheck": "tsc --noEmit",
+    "test": "bun test",
+    "test:clean": "CLEAN_TMP=1 bun test"
+  },
+  "devDependencies": {
+    "@g3nomaly/core": "^0.3.1",
+    "@types/bun": "^1.4.0",
+    "typescript": "~7.0.2",
+    "zod": "^4.4.3"
+  },
+  "license": "Elastic-2.0",
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/skills/agent/.claude-plugin/plugin.json

@@ -0,0 +1,7 @@
+{
+  "name": "agent",
+  "description": "Rules every agent session follows: the session bootstrap, its boundaries, and working in worktrees.",
+  "version": "0.1.0",
+  "license": "UNLICENSED",
+  "skills": ["./bootstrap", "./worktrees"]
+}

package/skills/agent/bootstrap/SKILL.md

@@ -0,0 +1,21 @@
+---
+name: bootstrap
+description: Session start checks and agent boundaries. Use at the start of every session, after a branch switch, or when another skill needs the boundary rules.
+disable-model-invocation: false
+---
+
+## Steps
+
+Run every session before any work, and after a branch switch.
+
+1. **Read** `CLAUDE.md` in full.
+2. **Get the file tree**: run `git ls-files --cached --others --exclude-standard`.
+3. **Compare** it against the tree you expect. On mismatch, output exactly `FILE TREE MISMATCH`, stop and ask. Do not guess.
+4. **State the branch**: output exactly `BRANCH: <name>`, from `git branch --show-current`. It must be `main` in the main checkout, unless the user asked you to work in a worktree (see the `/worktrees` skill). Otherwise stop and ask.
+
+Done when `BRANCH: <name>` is printed and no step stopped you.
+
+## Boundaries
+
+- **Air-gapped**: everything stays on disk. Never publish, push, upload or share anything to an external service.
+- **No workarounds**: when a tool call or permission is blocked, stop and report it.

package/skills/agent/bootstrap/agents/openai.yaml

@@ -0,0 +1,5 @@
+interface:
+  display_name: "Bootstrap"
+  short_description: "Session start checks: file tree, branch, and agent boundaries"
+policy:
+  allow_implicit_invocation: true

package/skills/agent/worktrees/SKILL.md

@@ -0,0 +1,21 @@
+---
+name: worktrees
+description: Work in a git worktree on its home branch and land the work there with a local squash merge. Use only when the user asks you to work in a worktree.
+disable-model-invocation: false
+---
+
+A worktree at `~/worktrees/<repo>/<x>` has the **home branch** `worktree/<x>`, which tracks local `main`. Work ends on the home branch. The user merges it into `main`.
+
+## Steps
+
+1. `git switch worktree/<x> && git pull --no-rebase --no-edit`
+2. `git switch -c <type>/<name>`, do the work, commit, and run the package's checks (see the `/code` skill)
+3. `git switch worktree/<x> && git pull --no-rebase --no-edit`
+4. `git merge --squash <type>/<name>`, then `git commit` with a subject and body covering the whole change
+5. Stop and report. Leave the feature branch in place.
+
+On conflict: `git merge --abort` (after a squash: `git reset --merge`), stop and report.
+
+## Branch types
+
+`feature`, `fix`, `refactor`, `chore`, `docs`, `snapshot` (backup before destructive operations), `demo` (not meant to merge), `experiment` (may never merge).

package/skills/agent/worktrees/agents/openai.yaml

@@ -0,0 +1,5 @@
+interface:
+  display_name: "Worktrees"
+  short_description: "Work on a worktree's home branch and land it with a local squash merge"
+policy:
+  allow_implicit_invocation: true

package/skills/coding/.claude-plugin/plugin.json

@@ -0,0 +1,7 @@
+{
+  "name": "coding",
+  "description": "How to write, check and document code, per language, and query a repository with analyze.",
+  "version": "0.1.0",
+  "license": "UNLICENSED",
+  "skills": ["./code", "./document", "./analyze"]
+}

package/skills/coding/analyze/SKILL.md

@@ -0,0 +1,32 @@
+---
+name: analyze
+description: Query and update the linked model of a repository with g3n-analyze: find code, docs, skills, decisions and tasks, see what uses or links to what, and rebuild the documentation site in analyze_out/. Use when asked where something is, what uses a type or function, what a decision affects, or to run g3n-analyze or regenerate the docs.
+---
+
+`g3n-analyze` scans a repository into one model of **nodes** and **edges**, and answers queries on it. Run it from the repository root as `bunx @g3nomaly/analyze <command>`; in the g3n monorepo, `bun packages/analyze/dist/cli.js <command>` after `bun run build` in `packages/analyze`.
+
+## Query
+
+1. **Find** the node: `search <words>`. It matches names first, then meaning. Done when a hit's `id` names what you want.
+2. **Read** it: `show <id>`. Text, signature, parameters, fields and every edge.
+3. **Follow** its edges: `refs <id>`. Add `--incoming` for what uses it, `--outgoing` for what it uses, `--edge <kind>` to keep one kind, such as `type` or `affects`.
+4. **Narrow** any of these with `--kind`, `--section` and `-n`. `list --kind <kind>` lists every node of a kind.
+
+Add `--json` when a script reads the output. A `<node>` may be an `id`, a file path or a name; a name that fits several nodes prints the candidates.
+
+A _member_, a parameter, field, operation or definition, is found by search but returns its _owner_: the function, the type or the file. Its exact `id` opens the member itself.
+
+Flags, kinds and edge kinds: [`references/commands.md`](references/commands.md).
+
+## Update
+
+- **Queries rescan by themselves.** The scan is cached in `analyze_out/cache/` and redone when a file changes. `--no-cache` forces it.
+- **Rebuild the site** with `create_docs`. It writes `analyze_out/index.html` and nothing else.
+- **Change what is scanned** in `.analyzeignore` at the root, written with the defaults on the first run. `--exclude <glob>` skips more for one run.
+- **Never edit `analyze_out/`.** It is output.
+
+What makes a repository show more, such as glossaries, decisions and doc tags: [`references/repository.md`](references/repository.md).
+
+## From code
+
+Hooks and scripts call the same queries as a typed library, without the CLI: [`references/api.md`](references/api.md).

package/skills/coding/analyze/agents/openai.yaml

@@ -0,0 +1,5 @@
+interface:
+  display_name: "Analyze"
+  short_description: "Query and rebuild the linked model of a repository with g3n-analyze"
+policy:
+  allow_implicit_invocation: true

package/skills/coding/analyze/references/api.md

@@ -0,0 +1,27 @@
+# Library
+
+`@g3nomaly/analyze` exports the queries as functions. They take the CLI options as fields, never print, and throw `OptionsError`, `QueryError` or `SourceError`.
+
+```ts
+import { createDocs, list, refs, search, show } from '@g3nomaly/analyze';
+
+const repo = '/home/me/app';
+const { hits } = await search({ repo, query: 'route price', limit: 5 });
+const node = await show({ repo, target: hits[0].id });
+const users = await refs({ repo, target: 'choose_route', incoming: true, edges: ['type'] });
+const tasks = await list({ repo, kinds: ['task'] });
+await createDocs({ repo });
+```
+
+| Field | Functions | CLI flag |
+|---|---|---|
+| `repo`, `skillDirs`, `docDirs`, `excludes`, `embeddings` | all | `--repo`, `--skills`, `--docs`, `--exclude`, `--no-embeddings` |
+| `from`, `cache` | queries | `--from`, `--no-cache` |
+| `kinds`, `section` | queries | `--kind`, `--section` |
+| `query`, `by`, `limit` | `search` | `<query>`, `--by`, `-n` |
+| `target` | `show`, `refs` | `<node>` |
+| `incoming`, `outgoing`, `edges` | `refs` | `--incoming`, `--outgoing`, `--edge` |
+| `title` | `createDocs` | `--title` |
+| `onWarning` | all | — |
+
+Warnings go to `onWarning` and are dropped without it.

package/skills/coding/analyze/references/commands.md

@@ -0,0 +1,54 @@
+# Commands
+
+| Command | Does |
+|---|---|
+| `create_docs` | Writes `analyze_out/index.html`, one offline HTML file |
+| `search <query>` | Finds nodes by words and by meaning |
+| `show <node>` | Prints one node in full |
+| `refs <node>` | Lists its edges, both ways |
+| `list` | Lists nodes in display order |
+
+## Flags
+
+| Flag | Commands | Does |
+|---|---|---|
+| `--repo <dir>` | all | Repository to read. Default: the working directory |
+| `--skills <dir>`, `--docs <dir>` | all | Read skills or docs from this directory only. Repeatable |
+| `--exclude <glob>` | all | Skip matching paths. Repeatable |
+| `--no-embeddings` | all | No search by meaning |
+| `--title <text>` | `create_docs` | Site title |
+| `--from <file>` | queries | Query a built `index.html` instead of scanning |
+| `--no-cache` | queries | Scan again even when nothing changed |
+| `--json` | queries | JSON instead of text |
+| `--kind <kind>` | queries | Only this kind. Repeatable |
+| `--section <name>` | queries | `skills`, `docs`, `code`, `database` or `tasks` |
+| `-n, --limit <n>` | `search`, `list` | Most results |
+| `--by <way>` | `search` | `name`, `meaning` or `both` |
+| `--incoming`, `--outgoing` | `refs` | One direction only |
+| `--edge <kind>` | `refs` | Only this edge kind. Repeatable |
+
+Each flag has an `ANALYZE_*` variable, such as `ANALYZE_REPO`. A flag wins over its variable.
+
+## Kinds
+
+- **Structure**: `folder`, `package`, `file`
+- **Code**: `namespace`, `class`, `interface`, `struct`, `enum`, `trait`, `type`, `function` (methods included)
+- **Docs and data**: `term`, `decision`, `table`, `query`
+- **Tasks**: `plan`, `phase`, `task`
+- **Members**, returned as their owner: `operation`, `definition`, `parameter`, `field`
+
+The JSON of a node has its `kind` and its `type`, the finer sort, such as `method` or `api`.
+
+## Edge kinds
+
+| Edge | From → to |
+|---|---|
+| `type` | parameter or field → its type |
+| `returns`, `throws` | function → type it returns or throws |
+| `extends` | type → type it extends or implements |
+| `mentions` | page or description → node it links to |
+| `uses` | text → glossary term |
+| `affects` | decision → node it is about |
+| `references` | table → table of its foreign key |
+| `reads`, `writes` | query → table |
+| `names`, `depends` | plan, phase or task → node it names, task it waits for |

package/skills/coding/analyze/references/repository.md

@@ -0,0 +1,13 @@
+# What analyze reads
+
+| Shows as | Write |
+|---|---|
+| **Skill** | A `SKILL.md` inside an AI directory: `.claude`, `.codex`, `.cursor`, `.gemini`, `.agents`, `.windsurf`, `.opencode`. Elsewhere it is a doc |
+| **Package** | A directory with a manifest: `package.json`, `pyproject.toml`, `Cargo.toml`, `go.mod`, `pom.xml`, `build.gradle`, `composer.json`, `.csproj`, `.gemspec`, `Gemfile`. A declared executable makes it an app |
+| **Glossary** | A `glossary.md`. Each term is a node, and its first use in any text links to it |
+| **Decisions** | A `decisions.md`. Each decision is a node; a link or inline code in it that names a node becomes an `affects` edge |
+| **Code docs** | Doc comments. `@param`, `@returns`, `@throws` and `@property` attach to the parameter, return value, error and field |
+| **Database** | `.sql` files. One with `CREATE TABLE` is a schema, any other a query |
+| **Tasks** | The task-manager tree in `docs/task-manager`, or the directory `.g3n.config.json` names |
+
+Inline code that names a type or function, such as `` `choose_route` ``, links to it from any text.

package/skills/coding/code/SKILL.md

@@ -0,0 +1,28 @@
+---
+name: code
+description: Standard code skill for writing and checking code. Includes toolchain references for each language.
+disable-model-invocation: false
+---
+
+## Rules
+
+Apply SOLID principles, DRY, and KISS. Use descriptive names for variables, functions, and classes.
+
+- **One domain per file**: schemas, selectors and business logic live in separate files. Split god objects.
+- **Strict typing**: per the language reference. Python passes `mypy` or `pyright`.
+- **Production grade**: handle errors explicitly, validate external input at the boundary, leave no dead code.
+- **No shims**: on a rename or refactor, update every call site. Leave no aliases.
+- **Config from the environment**: read configuration from environment variables through a schema.
+
+## Testing
+
+- Features in active development get no tests. The type checker and linters carry the structural checks.
+- Tests go in `tests/`, once a feature's API is stable.
+
+## code references
+
+Each language has a reference that names its toolchain, its commands and its rules.
+
+| Language | Reference | Files |
+|---|---|---|
+| TypeScript | [`references/typescript.md`](references/typescript.md) | `.ts` `.tsx` |

package/skills/coding/code/agents/openai.yaml

@@ -0,0 +1,5 @@
+interface:
+  display_name: "Code"
+  short_description: "Toolchain and check commands per language: install, typecheck, lint, test, build"
+policy:
+  allow_implicit_invocation: true

package/skills/coding/code/references/typescript.md

@@ -0,0 +1,26 @@
+# TypeScript
+
+Bun handles install, run, test and build. Run commands from inside the package directory.
+
+| Task | Command |
+|---|---|
+| Install | `bun install` |
+| Add a dependency | `bun add <pkg>`, or `bun add -d <pkg>` for dev |
+| Run a file | `bun <file>` |
+| Run a script | `bun run <script>` |
+| Run a tool once | `bunx <pkg>` |
+| Build | `bun run build` |
+
+## Checks
+
+| Check | Command | When |
+|---|---|---|
+| Typecheck | `bun run typecheck` | always |
+| Lint | `bun run lint` | when the package defines it |
+| Test | `bun test` | when the package has tests |
+
+## Rules
+
+- `strict: true` in `tsconfig.json`.
+- `unknown` and narrowing in place of `any`.
+- External input is parsed with zod at the boundary.

package/skills/coding/document/SKILL.md

@@ -0,0 +1,56 @@
+---
+name: document
+description: Docstrings and comments for functions and classes, and where the reasons behind code go. Use when writing or changing a function or class, or when another skill needs the documentation rules.
+disable-model-invocation: false
+---
+
+Documentation describes _what_ code does and _how_. The _why_ goes in `decisions.md`.
+
+These rules apply to existing docstrings too. **Rewrite docstrings that breaks them when applicable**, and never copy the style of one that does.
+
+## Files
+
+Line 1 of every file is a comment with its relative path. No file-level docstring.
+
+## Docstrings
+
+Functions, classes and other type declarations get a docstring; the language reference lists which. **A property, field or enum member is a tag in the docstring of its owner**, not a docstring of its own. 
+
+A _tag_ is a marked line in a docstring that documents one thing, such as `@param` in TypeScript.
+
+**What a tag can say goes in the docstring, never in a code comment.** Any tag the language has is fine.
+
+## Functions
+
+The function its docstring is declarative of _what_ / _how_ it works. Use @brief to summarize the function in one line or two lines.
+
+Tag a parameter or the return value when its name and type hide the meaning. Custom types are always tagged.
+
+## Classes
+
+A class docstring says:
+
+- what it does and holds,
+- which modules create and consume it,
+- how to create one.
+
+## Other types
+
+The summary says what the type _holds_. Tag its properties under the same rule as function parameters.
+
+## Comments
+
+An inline comment explains how code works when neither the code nor a tag shows it. Use sparingly!
+
+## Decisions
+
+A decision is a choice **the user** made, with its _why_, never the _how_. A choice made while implementing is not one.
+
+- **Never add an entry without the user's explicit approval.**
+- Decisions are never written in the code.
+
+## Languages
+
+The syntax for each language:
+
+- TypeScript: [`references/typescript.md`](references/typescript.md)

package/skills/coding/document/agents/openai.yaml

@@ -0,0 +1,5 @@
+interface:
+  display_name: "Document"
+  short_description: "Docstrings, @param and @returns, comments, and decisions.md for the why"
+policy:
+  allow_implicit_invocation: true

package/skills/coding/document/references/typescript.md

@@ -0,0 +1,131 @@
+# TypeScript
+
+TSDoc: a `/** */` block directly above the declaration.
+
+- **Declarations with a docstring**: functions, classes, interfaces, type aliases and enums.
+- **Summary**: `/** Adds two numbers. */` on one line. A longer block opens with `@brief` and the summary.
+- **Tags**: `@param name - text`, `@returns text`, and for the members of a class, interface, type or enum `@param name - text` or `@property name - text`. Any other TSDoc tag that fits is fine: `@throws {Type} When ...`, `@example`, `@see`, `@deprecated`.
+
+```ts
+/** Adds two numbers. */
+export function add(a: number, b: number): number {
+  return a + b;
+}
+
+/**
+ * @brief Retrieves a user by id.
+ * 
+ * @param userId - Surrogate key from the `users` table, not the auth provider's id.
+ * @returns Custom User class used by the authentication service, or `undefined` when no row matches.
+ */
+export async function getUser(userId: number): Promise<User | undefined> {
+  // ...
+}
+
+/**
+ * @brief Error for a file on disk that does not match its schema.
+ *
+ * Holds the path of the file and one issue per rejected field, and its message
+ * lists them all. Thrown by `parseFile` and by the readers in `filetree/`,
+ * `decisions/` and `vocabulary/` that check a file's layout by hand. Callers
+ * tell it apart from other errors with `instanceof FileValidationError`.
+ *
+ * @example
+ * throw new FileValidationError("/home/me/app/docs/task-manager/auth/auth.md", [
+ *   { field: "status", message: 'is "done"' },
+ * ]);
+ */
+export class FileValidationError extends Error {
+  readonly file: string;
+  readonly issues: FileValidationIssue[];
+
+  /**
+   * @brief Builds the message from the file path and every issue.
+   *
+   * @param file - Absolute path of the file that failed, e.g. `/home/me/app/docs/task-manager/auth/auth.md`.
+   * @param issues - Rejected fields, e.g. `{ field: "phases.0.status", message: "is required" }`.
+   */
+  constructor(file: string, issues: FileValidationIssue[]) {
+    // ...
+  }
+}
+
+/**
+ * @brief Entries a set of requests resolved to, and the requests that did not resolve.
+ *
+ * @property entries - Resolved entries by key, e.g. `emphasise`.
+ * @property unknown - Requests no source offers, e.g. `ghost@mine`.
+ * @property notes - Why an entry nobody named is in the set, e.g. `{ vocabulary: "dep of plan" }`.
+ */
+export interface Resolution {
+  entries: Map<string, SourceOffer>;
+  unknown: string[];
+  notes: Record<string, string>;
+}
+```
+
+## Bad
+
+Each one next to what is wrong with it. The examples above show the fix.
+
+```ts
+/** Holds the installed skills read from `skills.json`. */
+export class SkillRegistry {}
+```
+Too thin. It leaves out what the class holds, who creates and consumes it, and how to make one.
+
+```ts
+/** @param file - Path of the file that was read. */
+constructor(file: string, issues: FileValidationIssue[])
+```
+`file` doesn't say absolute or relative. `issues` is missing, while its type hides what goes in it.
+
+```ts
+/**
+ * @param issues - One entry per rejected field. `field` is the dotted path
+ *   as it reads in the file, such as `phases.0.status`, or `(whole file)`.
+ */
+```
+Prose about the type. One example value shows it faster: `` e.g. `{ field: "phases.0.status", message: "is required" }` ``.
+
+```ts
+/**
+ * Adds two numbers.
+ * @param a - The first number.
+ * @param b - The second number.
+ * @returns The sum.
+ */
+export function add(a: number, b: number): number
+```
+The tags repeat the signature. The summary line is enough.
+
+```ts
+/** Entries one request names. */
+function matchRequest(request: EntryRequest, offers: readonly SourceOffer[]): Match
+```
+A noun phrase that names the result, and no tags. The summary says what the function does: _Finds the entries one request names_. `EntryRequest`, `SourceOffer` and `Match` are custom types, so `request`, `offers` and the return value each need a tag.
+
+```ts
+/** Entries a set of requests resolved to. */
+export interface Resolution {
+  /** Resolved entries by key. */
+  entries: Map<string, SourceOffer>;
+  /** Requests no source offers. */
+  unknown: string[];
+}
+```
+A docstring on each property. Properties go in the interface's docstring as `@property` tags, as in `Resolution` above.
+
+```ts
+/**
+ * Resolves the dependencies of one entry against every offer.
+ *
+ * @param preferred - Source to take a key from when several offer it.
+ */
+```
+More than one line without `@brief`. It opens with `@brief Resolves the dependencies...`.
+
+```ts
+/** Loads a user by id. Uses a surrogate key because auth ids changed format in 2024. */
+```
+The _why_ belongs in `decisions.md`. The docstring says what and how.

package/skills/grilling/.claude-plugin/plugin.json

@@ -0,0 +1,7 @@
+{
+  "name": "grilling",
+  "description": "Relentless interviews that stress-test a plan, plus the domain model they feed.",
+  "version": "0.1.0",
+  "license": "UNLICENSED",
+  "skills": ["./grilling", "./grill-me", "./grill-with-docs", "./domain-modeling"]
+}

package/skills/grilling/domain-modeling/ADR-FORMAT.md

@@ -0,0 +1,47 @@
+# ADR Format
+
+ADRs live in `docs/adr/` and use sequential numbering: `0001-slug.md`, `0002-slug.md`, etc.
+
+Create the `docs/adr/` directory lazily — only when the first ADR is needed.
+
+## Template
+
+```md
+# {Short title of the decision}
+
+{1-3 sentences: what's the context, what did we decide, and why.}
+```
+
+That's it. An ADR can be a single paragraph. The value is in recording *that* a decision was made and *why* — not in filling out sections.
+
+## Optional sections
+
+Only include these when they add genuine value. Most ADRs won't need them.
+
+- **Status** frontmatter (`proposed | accepted | deprecated | superseded by ADR-NNNN`) — useful when decisions are revisited
+- **Considered Options** — only when the rejected alternatives are worth remembering
+- **Consequences** — only when non-obvious downstream effects need to be called out
+
+## Numbering
+
+Scan `docs/adr/` for the highest existing number and increment by one.
+
+## When to offer an ADR
+
+All three of these must be true:
+
+1. **Hard to reverse** — the cost of changing your mind later is meaningful
+2. **Surprising without context** — a future reader will look at the code and wonder "why on earth did they do it this way?"
+3. **The result of a real trade-off** — there were genuine alternatives and you picked one for specific reasons
+
+If a decision is easy to reverse, skip it — you'll just reverse it. If it's not surprising, nobody will wonder why. If there was no real alternative, there's nothing to record beyond "we did the obvious thing."
+
+### What qualifies
+
+- **Architectural shape.** "We're using a monorepo." "The write model is event-sourced, the read model is projected into Postgres."
+- **Integration patterns between contexts.** "Ordering and Billing communicate via domain events, not synchronous HTTP."
+- **Technology choices that carry lock-in.** Database, message bus, auth provider, deployment target. Not every library — just the ones that would take a quarter to swap out.
+- **Boundary and scope decisions.** "Customer data is owned by the Customer context; other contexts reference it by ID only." The explicit no-s are as valuable as the yes-s.
+- **Deliberate deviations from the obvious path.** "We're using manual SQL instead of an ORM because X." Anything where a reasonable reader would assume the opposite. These stop the next engineer from "fixing" something that was deliberate.
+- **Constraints not visible in the code.** "We can't use AWS because of compliance requirements." "Response times must be under 200ms because of the partner API contract."
+- **Rejected alternatives when the rejection is non-obvious.** If you considered GraphQL and picked REST for subtle reasons, record it — otherwise someone will suggest GraphQL again in six months.