feat(adhd): add ADHD output-shaping plugin (reauthor of i-have-adhd)#774
Conversation
## Summary New `adhd` plugin — one skill, `/adhd:shape` — that shapes the assistant's output for a reader with ADHD (and anyone who wants action-first, low-friction responses): lead with the concrete next action, number multi-step work, restate state across turns, cap and rank lists, give concrete time estimates, make wins visible, keep a flat error tone, and cut preamble, recap, and closers — plus override rules (explain / destructive-action confirm / debug spiral / ambiguity) and a pre-send check. Reauthored — not forked — from ayghri/i-have-adhd (MIT): the ten rules' substance is preserved and the prose rewritten; the wrapper is adapted to this marketplace's discovery discipline. Upstream auto-fired on ANY message (probabilistic always-on via skill selection); ours is on-demand with honest discovery triggers and no auto-fire, and its body is session-standing (one invocation shapes every response for the rest of the session). Design A (skill only). Deterministic zero-invocation always-on is deferred to a SessionStart hook (off by default) with a recorded trigger, because a `userConfig` boolean substitutes only into an already-invoked skill body and cannot auto-invoke — documented in the plugin README so it is not re-litigated. The README also documents mutual exclusion with terse-for-tokens output shapers such as caveman: opposite objectives on the same axis. - `plugins/adhd/.claude-plugin/plugin.json` — new, semver 0.1.0, MIT. - `plugins/adhd/skills/shape/SKILL.md` — the skill (10 rules + 5 facts + 4 overrides + pre-send check). - `plugins/adhd/skills/shape/evals/evals.json` — 5 cases (trigger/happy-path, session-standing, destructive-action guardrail, explain override, no-preamble anti-pattern). - `plugins/adhd/README.md`, `plugins/adhd/CHANGELOG.md` — docs + 0.1.0 entry. - `.claude-plugin/marketplace.json` — registration (category: personal); root README catalog regenerated. Zero-config, zero-prerequisite: no hooks, scripts, MCP, `userConfig`, `bin/`, egress, or cache reach-outs — cleanest plugin-acceptance trust posture. ## Verification ``` claude plugin validate ./plugins/adhd # passed claude plugin validate --strict . # passed (catalog) skill-quality check-skill.sh shape # PASS (0 err, 1 benign WARN) node scripts/generate-catalog.mjs --check # in sync bash scripts/check-changelog-parity.sh --check-bump origin/main # OK node scripts/validate-plugin-contracts.mjs # OK bash scripts/check-changed-skills.sh origin/main # 0 failed markdownlint-cli2 (README/CHANGELOG/SKILL) # 0 errors editorconfig-checker # exit 0; LF + final newline ``` ## Related - Reauthors ayghri/i-have-adhd (MIT): https://github.com/ayghri/i-have-adhd - Output-shape relative of, and mutually exclusive with, the third-party caveman plugin (https://github.com/JuliusBrussee/caveman). No linked issue Co-authored-by: Claude Opus <noreply@anthropic.com>
|
Claude finished @kyle-sexton's task in 1m 21s —— View job Security Review —
|
| Surface | Assessment |
|---|---|
| Code execution (hooks, bin/, scripts) | None — absent entirely |
| Remote MCP servers | None |
| Config secrets or credentials | None — zero-config |
Cache reach-outs (${CLAUDE_PLUGIN_DATA}) |
None — stateless |
| Data egress / network calls | None — purely behavioral |
| External runtime dependencies | None |
| Third-party trust delegation | None at runtime |
Plugin manifest (plugin.json): metadata fields only — name, version, description, author, license, keywords. The $schema field is an editor-validation hint; the Claude Code runtime ignores it at load time (confirmed in repo CLAUDE.md). No runtime network fetch.
Skill body (SKILL.md): pure markdown instruction text — no tool calls, no template variable substitution, no ${VAR} references, no hardcoded paths or PII. The session-standing scope ("shape every response for the rest of this session") is explicit and user-initiated. Critically, the override rules at lines 119–131 do not suppress safety guardrails — they explicitly require confirmation before destructive actions ("Safety outranks brevity").
Evals (evals.json): declarative test definitions only. The adversarial prompt in eval #3 ("wipe my local branch and force-push over main") is a test input string verifying the safety override — no execution surface.
Marketplace entry: source resolves to a local relative path (./plugins/adhd), category and tags are standard strings. No remote fetch.
Attribution links (in SKILL.md and README.md): informational text referencing the upstream MIT repo — no runtime dependency on external code; content is not fetched at load time.
Summary
Approved from a security standpoint. The plugin ships with zero attack surface expansion: no execution, no egress, no secrets, no external dependencies. Plugin-acceptance criteria from the repo playbook are fully satisfied.
|
Claude finished @kyle-sexton's task in 2m 9s —— View job PR Review: feat(adhd): add ADHD output-shaping plugin
SummaryThis is a clean, well-designed plugin with the minimal trust surface the platform prescribes. The Defect:
|
| Check | Result |
|---|---|
| Repo-agnostic (no hardcoded paths, repo names, env vars) | ✅ |
| Zero-config, zero-prerequisite | ✅ |
Plugin-form-safe (${CLAUDE_PLUGIN_ROOT} / ${CLAUDE_PLUGIN_DATA} only) |
✅ n/a — no file access |
Explicit semver version in plugin.json |
✅ 0.1.0 |
| MIT license | ✅ |
| No PII / secrets | ✅ |
Skill name follows imperative verb convention (shape) |
✅ |
user-invocable: true |
✅ |
| CHANGELOG present | ✅ |
| Evals present and cover key behavioral properties | ✅ 5 evals |
| Attribution of upstream MIT work | ✅ in plugin.json, SKILL.md, README.md, CHANGELOG.md |
| Security trust surface (no code exec, no egress, no MCP) | ✅ cleanest possible posture |
marketplace.json tag parity with plugin.json keywords |
❌ missing executive-function |
One concrete fix before merge: add "executive-function" to the adhd entry in .claude-plugin/marketplace.json. Everything else is non-blocking.
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 47034c9f3e
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
Addresses a review finding (Codex P2): MIT requires the original copyright and permission notice to travel with substantial portions of the work, and this plugin reauthors ayghri/i-have-adhd — preserving the ten rules' substance. An attribution line alone does not satisfy that; a proper notice retention does. - `plugins/adhd/LICENSE` (new) — MIT text carrying BOTH the upstream copyright (Copyright (c) 2026 Ayoub Ghriss, with the source URL) and Melodic Software's derivative copyright under one permission notice. - `plugins/adhd/README.md` — License section now points at the plugin's own LICENSE and states why the derivative ships one (pointer, not restatement). No behavior change; docs/licensing only. Co-authored-by: Claude Opus <noreply@anthropic.com>
|
Claude finished @kyle-sexton's task in 2m 2s —— View job Security Review —
|
| Surface | Assessment |
|---|---|
Code execution (hooks, bin/, scripts) |
None — absent entirely |
| Remote MCP servers | None |
| Config secrets or credentials | None — zero-config |
Cache reach-outs (${CLAUDE_PLUGIN_DATA}) |
None — stateless |
| Data egress / network calls | None — purely behavioral |
| External runtime dependencies | None |
| Third-party trust delegation | None at runtime |
Template variable injection (${VAR} substitution) |
Not present |
Path traversal in marketplace source field |
Not present (./plugins/adhd — no ..) |
GitHub Actions pull_request_target / workflow_run misuse |
No workflow files modified |
| Permission-widening to existing workflows | No workflow files modified |
Notes on individual files
plugin.json: Metadata only — name, version, description, author, license, keywords. No permissions, hooks, mcpServers, or dependencies keys. The $schema field is an editor-validation hint; the Claude Code runtime ignores it at load time.
SKILL.md: Pure markdown instruction text. No ${VAR} template variable substitution references; the single ${token} at line 99 is inside a backtick-escaped example string illustrating output format — it is not a plugin variable reference and will not be substituted. No hardcoded paths, PII, or secrets. The override rule requiring confirmation before destructive actions (lines 124–126) is a security-positive addition ("Safety outranks brevity").
evals.json: Declarative test definitions only. The adversarial prompt in eval #3 ("wipe my local branch and force-push over main") is a test input string verifying the safety override rule — no execution surface.
LICENSE: Standard MIT license text with dual copyright lines (Ayoub Ghriss + Melodic Software). Added by the latest commit (ecedbc4) to satisfy the upstream MIT requirement. No security concerns.
.claude-plugin/marketplace.json: The new adhd entry uses "source": "./plugins/adhd" — a relative path with no traversal components (..). Tags and category are plain strings. No remote fetch.
README.md and plugins/adhd/README.md: Documentation only. External links to ayghri/i-have-adhd and JuliusBrussee/caveman are attribution and usage-note text — no runtime dependency on external code; nothing is fetched at load time.
Summary
Approved from a security standpoint. The plugin ships with zero attack surface expansion across all eight changed files: no execution, no egress, no secrets, no external dependencies, no workflow modifications. Plugin-acceptance security criteria from the repo playbook are fully satisfied.
|
Claude finished @kyle-sexton's task in 1m 24s —— View job PR Review: feat(adhd): add ADHD output-shaping plugin
What this synchronize pushedOne commit: Resolved: MIT copyright complianceThe Codex P2 finding has been properly addressed. The The README License section explains why the derivative ships its own LICENSE file, which is the right level of documentation for this requirement. This satisfies the MIT "notice must travel with substantial portions" clause. ✅ Open defect:
|
| Item | Status |
|---|---|
| MIT copyright compliance (Codex P2) | ✅ Resolved in ecedbc4 |
executive-function tag in marketplace.json |
❌ Still missing — fix before merge |
| Gotchas / context-fade documentation | ℹ️ Non-blocking, deferred to next bump |
| All other plugin content (manifest, skill, evals, README, CHANGELOG) | ✅ No new issues |
One concrete fix remaining before merge: add "executive-function" to the adhd entry in .claude-plugin/marketplace.json.
Forward-merge to clear conflicts from #770/#774 and a playbooks 0.2.1 patch that landed on main. Resolved: playbooks plugin.json version 0.3.0 (my minor feature bump supersedes main's 0.2.1 patch); playbooks CHANGELOG keeps both entries (0.3.0 then 0.2.1). Catalog regenerated (in sync); no skill-quality conflicts.
Summary
New
adhdplugin — one skill,/adhd:shape— that shapes the assistant'soutput for a reader with ADHD (and anyone who wants action-first, low-friction
responses): lead with the concrete next action, number multi-step work,
restate state across turns, cap and rank lists, give concrete time estimates,
make wins visible, keep a flat error tone, and cut preamble, recap, and
closers — plus override rules (explain / destructive-action confirm / debug
spiral / ambiguity) and a pre-send check.
Reauthored — not forked — from ayghri/i-have-adhd (MIT): the ten rules'
substance is preserved and the prose rewritten; the wrapper is adapted to this
marketplace's discovery discipline. Upstream auto-fired on ANY message
(probabilistic always-on via skill selection); ours is on-demand with honest
discovery triggers and no auto-fire, and its body is session-standing (one
invocation shapes every response for the rest of the session).
Design A (skill only). Deterministic zero-invocation always-on is deferred
to a
SessionStarthook (off by default) with a recorded trigger, because auserConfigboolean substitutes only into an already-invoked skill body andcannot auto-invoke — documented in the plugin README so it is not
re-litigated. The README also documents mutual exclusion with terse-for-tokens
output shapers such as caveman: opposite objectives on the same axis.
Zero-config, zero-prerequisite: no hooks, scripts, MCP,
userConfig,bin/,egress, or cache reach-outs — cleanest plugin-acceptance trust posture.
Verification
The lone skill-quality WARN is "no Gotchas surface" — expected for a new skill
with no observed failure history.
Related
caveman plugin (https://github.com/JuliusBrussee/caveman).
No linked issue