From cea52264301221c13e234035a3b73271c4ead267 Mon Sep 17 00:00:00 2001 From: kisu Date: Fri, 7 Aug 2026 11:15:59 -0400 Subject: [PATCH] feat: make ADHD style automatic --- .claude-plugin/marketplace.json | 1 + .claude-plugin/plugin.json | 4 ++ LICENSE | 3 +- README.md | 91 ++++++++++++++++++++++++++++----- output-styles/adhd.md | 34 ++++++++++++ skills/adhd/SKILL.md | 7 ++- tests/manifest.test.mjs | 35 +++++++++++++ 7 files changed, 158 insertions(+), 17 deletions(-) create mode 100644 output-styles/adhd.md diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json index dcf005d..a3ba97d 100644 --- a/.claude-plugin/marketplace.json +++ b/.claude-plugin/marketplace.json @@ -9,6 +9,7 @@ { "name": "adhd", "description": "Tweet-sized, ADHD-friendly output style for Claude Code: turns verbose answers into short ones — action first, numbered steps, no filler.", + "license": "MIT", "source": "./", "category": "productivity" } diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.json index 449add4..1b7d2cc 100644 --- a/.claude-plugin/plugin.json +++ b/.claude-plugin/plugin.json @@ -1,6 +1,10 @@ { "name": "adhd", "description": "Turns verbose answers into tweet-sized ones. ADHD-friendly output style: short, concise answers — action first, numbered steps, one topic per answer, state restated every turn, no filler.", + "author": { + "name": "A dME Inc." + }, + "license": "MIT", "repository": "https://github.com/jjdmev2/adhd", "homepage": "https://github.com/jjdmev2/adhd" } diff --git a/LICENSE b/LICENSE index 18361d5..6594a2b 100644 --- a/LICENSE +++ b/LICENSE @@ -1,7 +1,6 @@ MIT License -Copyright (c) 2026 Kisu (tweet-me) -Portions copyright (c) 2026 Ayoub Ghriss (i-have-adhd) +Copyright (c) 2026 A dME Inc. Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal diff --git a/README.md b/README.md index 56b5a52..834b752 100644 --- a/README.md +++ b/README.md @@ -20,7 +20,11 @@ So I wrote one skill and shared it across every workflow I run. Now every answer ### Before / after -Real outputs. Same prompt — *"My Node app crashes on startup with 'Error: Missing API_KEY'. What's going on?"* — same model, skill off vs on: +Two examples, directly on this page. Same task, skill off vs on. + +#### Coding — missing `API_KEY` + +Prompt: *"My Node app crashes on startup with 'Error: Missing API_KEY'. What's going on?"* @@ -39,7 +43,7 @@ Real outputs. Same prompt — *"My Node app crashes on startup with 'Error: Miss + +
-**After — 292 chars, ~12s read** +**After — action first, ~12s read** > `API_KEY` env var isn't set. Fix: > @@ -47,7 +51,38 @@ Real outputs. Same prompt — *"My Node app crashes on startup with 'Error: Miss > 2. Add it to `.env` (or your shell env): `API_KEY=your_key_here` > 3. If using `.env`, confirm `dotenv` (or similar) is loaded before that check runs > -> Want me to grep your repo for where it's read? +> 1/1 done: startup has the key it needs. Next: restart the app. + +
+ +#### Research / report — decide what to do next + +Prompt: *"10 customer interviews: SSO came up in 3/10, all enterprise. Onboarding and reporting came up in 7/10. Should we build SSO now?"* + + + + + @@ -61,7 +96,7 @@ Any agent (Claude Code, Cursor, Codex, Cline, Windsurf, ~50 more): npx skills add jjdmev2/adhd ``` -Or as a Claude Code plugin — adds the `/adhd` command and an on/off switch: +Or as a Claude Code plugin — its forced output style applies this format to every main response while enabled. You can also invoke the skill manually with `/adhd:adhd`: ```bash git clone https://github.com/jjdmev2/adhd ./adhd @@ -71,7 +106,13 @@ claude plugin install adhd@adhd Pick one path, not both. Claude.ai web: **Settings → Capabilities → Skills** → upload [`skills/adhd/SKILL.md`](./skills/adhd/SKILL.md). -Wary of prompt plugins? This one is a single markdown file — read [SKILL.md](./skills/adhd/SKILL.md) before installing. No code, no dependencies. +For Codex, install with `npx skills add` above, then add this to your global `~/.codex/AGENTS.md` so it is the default for every task: + +```md +Always invoke and apply $adhd to every user-facing response unless the prompt starts with "ADHD off for this answer:". Preserve correctness, safety, and requested depth over brevity. +``` + +Wary of prompt plugins? The [core skill](./skills/adhd/SKILL.md) and [Claude Code output style](./output-styles/adhd.md) are plain Markdown. No code, no dependencies. ### The rules @@ -95,9 +136,10 @@ Concise mode shortens the answer. adhd rebuilds it for a brain that reads timeli ### Off / update / tune -- Off: `claude plugin disable adhd` +- One answer only: `ADHD off for this answer: explain the full trade-offs` +- Persistent Claude Code off: `claude plugin disable adhd` - Update: `cd ./adhd && git pull` -- Tune: edit [SKILL.md](./skills/adhd/SKILL.md), re-run `/adhd` +- Tune: edit [SKILL.md](./skills/adhd/SKILL.md), then invoke `/adhd:adhd` Turn it off for: deep-dive learning, postmortems, anything where you want every caveat. Test: if you'd *read* the five paragraphs, disable it. If you'd skim them, keep it on. @@ -120,7 +162,23 @@ Así que escribí un solo skill y lo compartí en todos mis workflows. Ahora cad ### Antes / después -Salida real (tabla arriba): misma pregunta, mismo modelo — 1.379 caracteres sin el skill, 292 con él. +Dos ejemplos, visibles aquí mismo. Misma tarea, skill apagado vs. encendido. + +#### Código — falta `API_KEY` + +Pregunta: *"Mi app de Node falla al iniciar con 'Error: Missing API_KEY'. ¿Qué pasa?"* + +| Sin el skill | Con el skill | +|---|---| +| **Antes — 1.379 caracteres, ~60 s**

Explica que la variable no está definida, enumera causas posibles y sigue con varios párrafos. | **Después — acción primero, ~12 s**

`API_KEY` no está definida. 1. Encuentra dónde se lee. 2. Agrégala a `.env`. 3. Carga `dotenv` antes de validarla.

**Estado:** 1/1 listo; reinicia la app. | + +#### Investigación / reporte — decidir qué sigue + +Pregunta: *"10 entrevistas: SSO apareció en 3/10, todos enterprise. Onboarding y reportes aparecieron en 7/10. ¿Construimos SSO ahora?"* + +| Sin el skill | Con el skill | +|---|---| +| **Antes — el reporte largo**

Resume seguridad, onboarding, compras, precios, integraciones y reportes. SSO aparece varias veces, con importancia distinta según el segmento. | **Después — evidencia → decisión → acción**

**Decisión:** no construir SSO este sprint.

**Evidencia:** 3/10 lo pidieron; los tres son prospectos enterprise. Onboarding y reportes aparecieron en 7/10.

1. Dejar SSO como requisito enterprise. 2. Arreglar onboarding primero. 3. Revisar tras cinco entrevistas enterprise más.

**Estado:** decisión tomada; próximo corte: 5 entrevistas. | ### Instalar — 30 segundos @@ -130,7 +188,7 @@ Cualquier agente (Claude Code, Cursor, Codex, Cline, Windsurf, ~50 más): npx skills add jjdmev2/adhd ``` -O como plugin de Claude Code — agrega el comando `/adhd` y un interruptor de encendido/apagado: +O como plugin de Claude Code — su estilo de salida forzado aplica este formato a cada respuesta principal mientras esté activo. También puedes invocarlo a mano con `/adhd:adhd`: ```bash git clone https://github.com/jjdmev2/adhd ./adhd @@ -140,7 +198,13 @@ claude plugin install adhd@adhd Elige un camino, no ambos. Claude.ai web: **Settings → Capabilities → Skills** → sube [`skills/adhd/SKILL.md`](./skills/adhd/SKILL.md). -¿Desconfías de los plugins de prompts? Este es un solo archivo markdown — lee [SKILL.md](./skills/adhd/SKILL.md) antes de instalar. Sin código, sin dependencias. +Para Codex, instala con `npx skills add` arriba y agrega esto a tu `~/.codex/AGENTS.md` global para que sea el formato por defecto en cada tarea: + +```md +Always invoke and apply $adhd to every user-facing response unless the prompt starts with "ADHD off for this answer:". Preserve correctness, safety, and requested depth over brevity. +``` + +¿Desconfías de los plugins de prompts? El [skill principal](./skills/adhd/SKILL.md) y el [estilo de salida de Claude Code](./output-styles/adhd.md) son Markdown plano. Sin código, sin dependencias. ### Las reglas @@ -158,9 +222,10 @@ Cinco más en [SKILL.md](./skills/adhd/SKILL.md) (en inglés — el skill le hab ### Apagar / actualizar / ajustar -- Apagar: `claude plugin disable adhd` +- Solo una respuesta: `ADHD off for this answer: explica todos los trade-offs` +- Apagar Claude Code de forma persistente: `claude plugin disable adhd` - Actualizar: `cd ./adhd && git pull` -- Ajustar: edita [SKILL.md](./skills/adhd/SKILL.md), vuelve a correr `/adhd` +- Ajustar: edita [SKILL.md](./skills/adhd/SKILL.md), vuelve a correr `/adhd:adhd` Apágalo para: aprendizaje a fondo, postmortems, cualquier cosa donde quieras cada detalle. Prueba: si *leerías* los cinco párrafos, apágalo. Si los saltearías, déjalo encendido. @@ -169,4 +234,4 @@ Prueba: si *leerías* los cinco párrafos, apágalo. Si los saltearías, déjalo --- -Inspired by [i-have-adhd](https://github.com/ayghri/i-have-adhd) by Ayoub Ghriss · MIT +A dME Inc. · [MIT](./LICENSE) diff --git a/output-styles/adhd.md b/output-styles/adhd.md new file mode 100644 index 0000000..b0b7a02 --- /dev/null +++ b/output-styles/adhd.md @@ -0,0 +1,34 @@ +--- +name: ADHD +description: ADHD-friendly answers that are concise, action-first, and easy to scan +keep-coding-instructions: true +force-for-plugin: true +--- + +Use this response style for every main-conversation answer. Apply it alongside task-specific instructions; change how the answer lands, not the quality of the work. + +## One-answer opt-out + +If the user's prompt starts with `ADHD off for this answer:`, suspend the compression rules for that answer only. Re-enable them automatically on the next user message. Never suspend correctness or safety. + +## Default response contract + +1. Tweet first. Fit the whole answer in roughly 280 characters when the task allows it. +2. Put the action, decision, result, or exact cause first. In research and reports, separate evidence from inference, name unknowns, and never invent missing facts, sources, or measurements. +3. Number multi-step work. Keep one bounded action per step and no more than five items in one list. +4. Keep one topic per answer. Offer at most one useful follow-up thread instead of dumping side issues. +5. Restate meaningful progress across turns, using concrete state such as `3/5 done; next: backfill`. +6. Use real time ranges instead of vague effort words. +7. Make wins observable: say what works and how the user can verify it. +8. Report errors as cause + fix; add blast radius for production incidents. Use zero drama. +9. Cut filler, empty hedges, preambles, recaps, generic closers, and meta-commentary about the prompt or style. +10. Go longer rather than becoming vague, cryptic, unsafe, or incomplete. + +## Go long when needed + +1. Confirm before destructive or consequential actions. +2. Explain fully when the user asks for an explanation or walkthrough; keep it skimmable with short headers. +3. On the third `still broken`, stop patching, name the questionable assumption, and ask one diagnostic question. +4. Ask one short clarifying question when guessing would likely waste a round trip. + +Correctness, safety, required caveats, and explicitly requested depth always override brevity. diff --git a/skills/adhd/SKILL.md b/skills/adhd/SKILL.md index 997709f..be3b32d 100644 --- a/skills/adhd/SKILL.md +++ b/skills/adhd/SKILL.md @@ -1,11 +1,11 @@ --- name: adhd -description: Shape output for a reader with ADHD — answers read like a tweet on X, short and straightforward, every character counts. Use this skill when responding to ANY user message, including coding tasks, debugging, explanations, planning, and casual conversation. Lead with the action, number the steps, keep one topic per answer, restate state across turns, give real time estimates, and make wins visible. Trigger even on casual messages and even when the user did not ask for brevity. +description: Always use for every message, even if unasked — coding, debugging, research, reports, planning, explanations, and chat. Shape output for an ADHD reader — concise, action-first, numbered when multi-step, one topic, visible state, real time estimates, and no filler. Apply alongside task-specific skills. Correctness, safety, and requested depth override brevity. --- @@ -111,6 +111,8 @@ Start at the answer. Stop when it's answered. Four cases break the 280 habit. In THREAD mode the length changes; the filler rules do not — still no intro, no outro, no recap. +If the prompt starts with `ADHD off for this answer:`, suspend the compression rules for that answer only. Re-enable them automatically on the next user message. The opt-out never disables correctness or safety. + 1. Destructive action ahead (`rm -rf`, force push, dropping a table, schema migration)? Confirm first. Safety beats brevity. 2. The user said "explain" or "walk me through"? Explain fully, add headers so it skims. Do not second-guess. 3. Third turn of "still broken"? Stop patching. Name the assumption that might be wrong. Ask one diagnostic question. @@ -124,6 +126,7 @@ The failure mode of this skill is over-application. Watch for: 2. Terse to cryptic. An answer that forces a "wait, what?" follow-up costs the exact round trip this skill exists to prevent. 3. Thread abuse. One answer split across five 🧵 prompts is worse than one thread. 4. State as filler. "3/5 done" earns its characters only when the numbers change. +5. Confident compression. In research and reports, separate evidence from inference, name unknowns, and never invent missing facts, sources, or measurements. This style trades length for speed. Never trade away safety or correctness. diff --git a/tests/manifest.test.mjs b/tests/manifest.test.mjs index 6d46ccd..f4fb0a2 100644 --- a/tests/manifest.test.mjs +++ b/tests/manifest.test.mjs @@ -8,6 +8,8 @@ const plugin = JSON.parse(read('.claude-plugin/plugin.json')) const marketplace = JSON.parse(read('.claude-plugin/marketplace.json')) const readme = read('README.md') const skill = read('skills/adhd/SKILL.md') +const outputStyle = read('output-styles/adhd.md') +const license = read('LICENSE') test('manifest names agree', () => { assert.equal(plugin.name, marketplace.name) @@ -22,6 +24,25 @@ test('README install commands match the manifests, in both languages', () => { assert.ok(npx >= 2, `expected npx install line in EN and ES sections, found ${npx}`) }) +test('MIT license metadata and file agree', () => { + assert.equal(plugin.license, 'MIT') + assert.equal(plugin.author.name, 'A dME Inc.') + assert.equal(marketplace.plugins[0].license, 'MIT') + assert.match(license, /^MIT License\n\nCopyright \(c\) 2026 A dME Inc\.\n\nPermission is hereby granted,/) + assert.doesNotMatch(license, /Ayoub|i-have-adhd|tweet-me/i) +}) + +test('README shows both examples and only the dME MIT footer', () => { + assert.match(readme, /^#### Coding — missing `API_KEY`$/m) + assert.match(readme, /^#### Research \/ report — decide what to do next$/m) + assert.match(readme, /^#### Código — falta `API_KEY`$/m) + assert.match(readme, /^#### Investigación \/ reporte — decidir qué sigue$/m) + assert.match(readme, /Always invoke and apply \$adhd/) + assert.match(readme, /ADHD off for this answer:/) + assert.match(readme, /A dME Inc\. · \[MIT\]\(\.\/LICENSE\)\n$/) + assert.doesNotMatch(readme, /Ayoub|i-have-adhd|Inspired by/i) +}) + test('SKILL.md frontmatter stays parseable and within limits', () => { const m = skill.match(/^---\n([\s\S]*?)\n---\n/) assert.ok(m, 'frontmatter block missing') @@ -32,6 +53,20 @@ test('SKILL.md frontmatter stays parseable and within limits', () => { // a bare ": " inside an unquoted YAML scalar breaks parsing and silently disables the skill assert.ok(!desc[1].includes(': '), 'description contains an unquoted ": "') assert.ok(desc[1].length <= 1024, `description is ${desc[1].length} chars (limit 1024)`) + assert.ok(desc[1].startsWith('Always use for every message, even if unasked'), 'always-on trigger must be first') + assert.match(desc[1].slice(0, 104), /coding.*debugging.*research/, 'key triggers must survive catalog truncation') + assert.match(skill, /ADHD off for this answer:/) +}) + +test('Claude output style is forced, coding-safe, and supports one-answer opt-out', () => { + const m = outputStyle.match(/^---\n([\s\S]*?)\n---\n/) + assert.ok(m, 'output style frontmatter block missing') + assert.match(m[1], /^keep-coding-instructions:\s*true$/m) + assert.match(m[1], /^force-for-plugin:\s*true$/m) + assert.match(outputStyle, /ADHD off for this answer:/) + assert.match(outputStyle, /Re-enable them automatically on the next user message/) + assert.match(outputStyle, /never invent missing facts, sources, or measurements/) + assert.match(outputStyle, /Correctness, safety, required caveats, and explicitly requested depth always override brevity/) }) test('SKILL.md "Good:" examples practice rule 1 (≤280 chars)', () => {
+ +**Before — the report dump** + +> The interviews reveal a number of themes around security, onboarding, procurement, pricing, integrations, and reporting. SSO came up repeatedly, although its importance varied by customer segment. A more comprehensive analysis follows… + + + +**After — evidence → decision → action** + +> **Decision:** do not build SSO this sprint. +> +> **Evidence:** 3/10 asked for it; all three are enterprise prospects. Onboarding and reporting appeared in 7/10. +> +> 1. Keep SSO as an enterprise requirement, not the next build. +> 2. Ship onboarding friction fixes first. +> 3. Recheck after five more enterprise interviews. +> +> **State:** decision made; next research checkpoint: 5 interviews.