@joaomj/pi-attention-span 0.8.0

package/README.zh-CN.md

@@ -0,0 +1,315 @@
+<p align="center">
+  <img src="assets/banner.svg" alt="Attention Span — 关注注意力，而非 token" width="820">
+</p>
+
+<p align="center">
+  <a href="https://github.com/alexgreensh/attention-span/releases"><img src="https://img.shields.io/github/v/release/alexgreensh/attention-span?label=%E7%89%88%E6%9C%AC&color=6f42c1" alt="最新版本"></a>
+  <img src="https://img.shields.io/github/directory-file-count/alexgreensh/attention-span/output-styles?type=file&extension=md&label=%E9%A3%8E%E6%A0%BC&color=blue" alt="风格数量">
+  <img src="https://img.shields.io/badge/%E5%B7%A5%E4%BD%9C-%E6%9C%AA%E5%8F%97%E5%BD%B1%E5%93%8D-2ea44f" alt="工作未受影响（隐藏测试基准）">
+  <a href="LICENSE"><img src="https://img.shields.io/github/license/alexgreensh/attention-span?color=orange" alt="AGPL-3.0"></a>
+  <img src="https://img.shields.io/badge/%E9%80%82%E7%94%A8%E4%BA%8E-Claude%20Code-d97757" alt="适用于 Claude Code">
+  <a href="https://github.com/alexgreensh/attention-span/stargazers"><img src="https://img.shields.io/github/stars/alexgreensh/attention-span?style=social" alt="Stars"></a>
+</p>
+
+<p align="center"><img src="assets/hero.png" alt="Attention Span 吉祥物" width="900"></p>
+
+<p align="center"><a href="README.md">English</a> · <a href="README.es-ES.md">Español</a> · <b>中文</b></p>
+
+一小组给 Claude Code 用的[输出风格](https://code.claude.com/docs/en/output-styles)，只改变它*怎么跟你说话*，不改变它怎么写代码。答案先行、大白话、易于扫读。每个风格都是一个 markdown 文件，放进去、切换开启即可。
+
+「默认简洁」的规则首先是善待你的注意力。顺带削减了 Claude 的输出，是受欢迎的副产品，而不是目的。
+
+目前有三款：**Attention-kind**（旗舰款）、**Spartan**（极简、零温度）、**Rundown**（TL;DR 简报）。每一款下面都有各自的章节。
+
+## Attention-kind
+
+一款对 ADHD（注意力缺陷）友好的风格。Claude 答案先行、保持简短、去掉术语，只在真正值得你注意的地方展开。每个要点都有空行隔开、用 `→` 标记，重点词加**粗**，所以你只扫读粗体也能拿到完整答案。
+
+底层的工程能力完全一样。变的只是表达方式。
+
+**适合谁：** 任何把注意力当作稀缺资源的人。ADHD、疲惫、正在心流里，或者只是受够了大段文字。
+
+### 前后对比
+
+问题：**「新做一个社交 app，数据库该用 PostgreSQL 还是 MongoDB？」** 同一个答案，套用风格前后的样子。
+
+<table>
+<tr>
+<th align="left" width="50%">默认 &nbsp;·&nbsp; 430 词</th>
+<th align="left" width="50%">Attention-kind &nbsp;·&nbsp; 94 词</th>
+</tr>
+<tr valign="top">
+<td>
+
+对于新的社交 app，先从 PostgreSQL 开始，改选 MongoDB 的门槛很高。社交 app 天生就是关系密集型的：用户关注用户、帖子属于用户、评论属于帖子、点赞把用户和帖子连起来。这是一张连接之网，正是关系型数据库被设计出来处理的东西。在 MongoDB 里，你要么把相关数据塞进一条记录里、跟大小上限较劲，要么把它们拆开、最后还是在应用代码里把它们重新拼回去。信息流的问题让这更糟：时间线、「你关注的人的帖子」、共同好友查询，全都依赖 Postgres 用一条查询就能完成的那种交叉引用。你还自带一致性，因为关注数和「我是不是已经点过赞了」这类检查需要真正的事务…… *[后面还是这样一直写下去]*
+
+</td>
+<td>
+
+**→ 用 PostgreSQL。** 社交 app 全是关系（好友、关注、点赞），而 Postgres 原生就能处理。适合约 90% 的新社交 app。
+
+**→ 灵活性照样在。** 它的 JSONB 字段能在同一个数据库里存无模式数据，让你不离开 Postgres 就拿到 MongoDB 那种无模式的自在。
+
+**→ 只有在以下情况才选 MongoDB：** 你的数据是彼此无关联的独立文档，而且第一天就需要极大的写入量。
+
+**→ MongoDB 的早期陷阱：** 半年后，「用户」有五种不同的形状，且没有干净的补救办法。Postgres 会强制结构。
+
+**→ 下一步：** 从托管 Postgres 起步（Supabase、Neon、RDS）。
+
+</td>
+</tr>
+</table>
+
+同样的信息。其中一个你一眼就能读完。
+
+### 真的有用吗？（已测量、可复现）
+
+这个基准把「工作」和「输出」分开衡量，头条数字**不用任何 LLM 裁判**。每个数字都能从本仓库复现。[完整说明与可运行的测试框架。](benchmarks/results/2026-08-11-benchmark.md)
+
+- **工作原封不动。** 12 个带隐藏测试套件的编码任务，无风格 vs 有风格：通过率相等（**都是 97%**，属于正常波动范围）。没有裁判，只有测试通过与否。
+- **输出平均短约 43%**（中位数 41%），在真正要紧的**冗长回答上短 50-71%**；本来就短的回答几乎不变。
+- **你大约 6 个词就能抓住要点，而不是约 40 个词。** 答案出现在第一行的比例是 **75%**，而默认只有 **3%**。（可读性评分在这里不适用，它们只看词长，看不出一堵文字墙。）
+- **88% 的交付物干净利落**，对比无风格时的 12%：你要一条消息或一次 commit，拿到的就是那个，没有包装。
+
+更短、更清楚、一眼就能领会，同时工作原封不动。我们不是说它产出更好的答案，那不是它的用途。
+
+### 有哪些变化
+
+- **答案先行。** 结论放第一行。不做铺垫。
+- **默认简短。** 说完足以完整回答的最少内容，然后就停。
+- **只在关键处展开**，让篇幅本身成为重要性的信号。
+- **大白话。** 少见的技术术语给一个五词以内的解释，且只给一次。
+- **为扫读而生。** `→` 标记、大量粗体、要点之间有真正的空行。
+- **不重复。** 每个要点只做一个独立论证，绝不复述或反复论证。
+- **长任务会重新锚定**，且一次只问一个问题，让你永远不丢线索。
+- **注释也一样。** 代码注释继承「解释为什么」的大白话规则，但绝不带聊天里的格式。
+
+## Spartan
+
+<p align="center"><img src="assets/cat-spartan.png" alt="一只戴斯巴达头盔的猫，把激光对准一行点亮的字" width="860"></p>
+
+极简模式，把温度去掉。和 Attention-kind 一样的箭头和粗体，但直白、命令式，不铺垫、不过渡，最大压缩。适合埋头干活、只要信号不要对话的时候。
+
+问题：**「这周三个优先事项，只有做两个的余地，我该怎么决定砍哪个？」** 两个都是 Opus 5 的真实评测输出。
+
+<table>
+<tr>
+<th align="left" width="50%">默认 &nbsp;·&nbsp; 310 词</th>
+<th align="left" width="50%">Spartan &nbsp;·&nbsp; 168 词</th>
+</tr>
+<tr valign="top">
+<td>
+
+砍掉那个通不过最便宜检验的：如果它推迟一周，谁真正会感到疼、疼多少。把三个都过一遍四个快速筛子，输的那个通常自己就掉出来了。延迟的后果：你三个里大概有两个的截止日期是你自己发明的软日期，一个是真的，有人在等、下游有依赖、有一扇会关上的窗。从自己强加的那堆里砍，绝不从「有人被你卡住」的那堆里砍。可逆性：有些事拖得越久越难，有些下周做也一样容易，所以砍掉成本曲线平的那个。除了你还有谁负责它：如果一个优先事项能被委派、或者别人能做到 80%，那它比只有你能做的那个更该砍…… *[后面还是这样一直写下去]*
+
+</td>
+<td>
+
+**→ 按「不做的代价」排序，不按投入或兴趣。** 逐个问：这个推迟一周，会有什么坏掉？后果最轻的那个砍掉。
+
+**→ 砍掉可逆的那个。** 如果一个任务能等、能委派、或事后重启且无惩罚，砍掉它。守住任何有**硬截止**或有**依赖**、会卡住别人的事。
+
+**→ 做后悔测试。** 周五晚上，哪个没做完的任务最扎心？留下那个。你会耸耸肩的那个就是你要砍的。
+
+**→ 把吵闹和重要分开。** 冲你喊得最凶的优先事项，往往只是最**焦虑**的，不是最有价值的。按影响砍，别按音量。
+
+**→ 别把三个都做一半。** 两个做完胜过三个各 66%。在第三个上做的半截活是陷阱，它感觉高产、却什么都交付不出。
+
+**→ 大声地砍。** 现在就告诉受影响的人，别等周五。你标出来的砍是一个决定，你藏起来的砍是一个**延后爆发的失败**。
+
+</td>
+</tr>
+</table>
+
+和 Attention-kind 一样的「只改风格」保证：更短、更易扫读，工作原封不动。见[基准](benchmarks/results/2026-08-11-benchmark.md)。
+
+## Rundown
+
+<p align="center"><img src="assets/cat-rundown.png" alt="Rundown 的猫把激光对准一份清单，其中一行点亮" width="860"></p>
+
+简报风格。以 **TL;DR** 开头，用 ✅ / 🟡 / ⬜ 清单展示状态，用 emoji 标注接下来的选项。为状态更新和站会而生。**它优化的是可读性和可扫读性，不是简洁**，所以当清楚比短更重要时用它。内置一道防线，防止它编造你从未给出的状态。
+
+问题：**「总结一下招聘进展：20 位申请人，5 位初筛，2 场面试，还没发 offer，一位强候选人正在流失。」** 两个都是 Opus 5 的真实评测输出。
+
+<table>
+<tr>
+<th align="left" width="50%">默认 &nbsp;·&nbsp; 一段读的文字</th>
+<th align="left" width="50%">Rundown &nbsp;·&nbsp; 一块扫的看板</th>
+</tr>
+<tr valign="top">
+<td>
+
+招聘目前是漏斗顶部厚、底部薄。二十份申请进来，五份初筛，两场面试已约。还没有 offer 发出去，而这道缺口就是问题：最强的候选人之一正在冷下来，而流程却在空转。数字：申请 20，初筛 5，已约面试 2，发出 offer 0，有风险 1 位正在流失的强候选人。判断：这是速度问题，不是供给问题。漏斗上部健康，但没有一个转化成 offer，最好的人选正在飘走。价值最高的动作是在延迟替我们做决定之前，加速那位正在流失的候选人。瓶颈：offer 阶段…… *[后面还是这样一直写下去]*
+
+</td>
+<td>
+
+TL;DR：漏斗上部健康，但终点线卡住了，你最好的候选人快走了。
+
+**招聘漏斗**
+- ☑️ **申请进来：** 20 份来源
+- ☑️ **已初筛：** 20 中的 5 份完成
+- 🟡 **面试：** 已约 2 场，尚未进行
+- ⬜ **Offer：** 未起草、未发出
+
+🔴 **阻塞点：** 一位强候选人正在流失。没有 offer 动作，就等于默认放弃他们。
+
+**你的一步：**
+- 🚀 加速那位强候选人，今天就直接跳到谈 offer
+- 📞 在决定前把已约的 2 场面试跑完
+- 📋 从没碰过的 15 份申请里多筛一些做备选
+- ✍️ 现在就把 offer 起草好，随时能发
+
+选一个：现在就保住候选人，还是跑完整流程、承担失去他们的风险？
+
+</td>
+</tr>
+</table>
+
+## 真的想削减你的 token 账单吗？
+
+Attention Span 的目的，是让你的智能体的回答变得可读、一眼能领会。那些回答上更轻的 token 开销是一份受欢迎的副产品。如果削减 token 开销才是你真正的目标，那更大的成本是你智能体做的*工作*，而不是它怎么说话，有两个姐妹工具正对着这一点下手，和这些风格天然配套：
+
+<p align="center"><img src="assets/save-tokens.png" alt="Outsourcerer 巫师和 Attention Span 的猫用 Token Optimizer 吸走幽灵 token" width="900"></p>
+
+**[Token Optimizer](https://github.com/alexgreensh/token-optimizer)** 直击大多数工具从不触碰的三层 token 浪费：
+
+- **结构层**，例如臃肿的配置、没用的 skill、过期的记忆
+- **运行层**，例如冗长的输出、重复读取
+- **行为层**，例如模型路由错误、缓存过期、重试循环
+
+……每一层里还不止这些。在此之上，它压缩你的输出栈，为你的工作做检查点并恢复，让你的会话在压缩（compaction）后仍然连续，并把省下的每个 token 和每一块钱放到一个实时看板上。它还是唯一一个衡量你上下文质量并据此调整的工具，因为一个更便宜、却把活干得更差的会话，根本算不上省。
+
+*支持 Claude Code、Codex、OpenCode、OpenClaw、Hermes 和 Copilot。*
+
+**[Outsourcerer](https://github.com/alexgreensh/outsourcerer)** —— 待在你最喜欢的那个智能体的同一个会话里。它在后台：
+
+- 在你已经付费的那些模型和框架之间调度一支小队
+- **按基准而非只按价格**，为每个任务挑最好的那个
+- 检查它们的工作，并在每个引擎里盯着你的额度
+
+驾驶舱还是你的；重活在别处发生。
+
+*可用于 Claude Code、Codex、Antigravity、Devin、Droid、Cursor、Warp 和 Hermes。*
+
+Attention Span 削减 Claude 说多少。这两个则管着你整个技术栈花多少。
+
+## 安装
+
+**1.** 把风格放进你的 output-styles 文件夹。全局（所有项目）：
+
+```bash
+mkdir -p ~/.claude/output-styles
+curl -o ~/.claude/output-styles/attention-kind.md \
+  https://raw.githubusercontent.com/alexgreensh/attention-span/main/output-styles/attention-kind.md
+```
+
+或者放进某个单独项目里的 `.claude/output-styles/`。
+
+**2.** 在 `~/.claude/settings.json` 里把它设为默认。设一次，之后每个会话都开着，永久生效：
+
+```json
+{ "outputStyle": "Attention-kind" }
+```
+
+**3.** 重启或 `/clear`。就这样。
+
+**不想改 JSON？** 装上 `/style` 命令，它替你做第 2 步：
+
+```bash
+mkdir -p ~/.claude/commands
+curl -o ~/.claude/commands/style.md \
+  https://raw.githubusercontent.com/alexgreensh/attention-span/main/commands/style.md
+```
+
+然后 `/style` 会弹出你已安装风格的列表。`/style spartan` 直接设一个。`/style default` 把内置风格换回来。
+
+它会在 `~/.claude/output-styles/` 和某个项目的 `.claude/output-styles/` 里查找。全局风格写进 `~/.claude/settings.json`。项目风格写进 `.claude/settings.local.json`，所以它不会进到你队友的检出里。
+
+**已经装过了？** 风格会有更新。查一下你在哪个版本，和上面的[版本徽章](https://github.com/alexgreensh/attention-span/releases)对一下：
+
+```bash
+grep attention-span ~/.claude/output-styles/*.md
+```
+
+落后了？重跑第 1 步的安装命令，用最新版覆盖。
+
+想先试用一个会话？运行 `/config`，在 *Output style* 里选它，试到满意后再按上面设成默认。
+
+**成本：** 约 650 个 token，每个会话加载一次，首次请求后即被缓存。基准测得输出短约 43%，所以首次回复之后，这点输入成本可以忽略不计。
+
+## 配合其他智能体使用
+
+风格正文是纯 markdown，没有任何 Claude 专属行为。唯一属于 Claude Code 的部分，是每个文件顶部的 YAML frontmatter（`/config` 选择器读取的 `name`/`description` 块）。其他智能体会忽略 frontmatter 或被它卡住，所以安装时会把它剥掉。
+
+每个风格文件在 frontmatter 之后有一个 `<!-- body-start -->` 标记。剥离命令就是一条 `sed`：
+
+```bash
+curl -sfL <raw-url> | sed '1,/<!-- body-start -->/d'
+```
+
+这样就得到干净的正文 markdown，可以直接放进任何智能体的规则或指令文件里。
+
+### 各智能体安装方式
+
+**Devin**（全局，通过 Windsurf 兼容层）：
+
+```bash
+mkdir -p ~/.codeium/windsurf/memories
+curl -sfL https://raw.githubusercontent.com/alexgreensh/attention-span/main/output-styles/attention-kind.md -o /tmp/attention-span.md \
+  && sed '1,/<!-- body-start -->/d' /tmp/attention-span.md > ~/.codeium/windsurf/memories/attention-kind.md
+```
+
+或项目级：仓库根目录的 `.windsurf/rules/attention-kind.md`。
+
+**Codex**（追加到全局 `AGENTS.md`，用注释围栏（fence marker）保证幂等）：
+
+```bash
+mkdir -p ~/.codex
+curl -sfL https://raw.githubusercontent.com/alexgreensh/attention-span/main/output-styles/attention-kind.md -o /tmp/attention-span.md \
+  && { printf '\n<!-- attention-span:start -->\n'; sed '1,/<!-- body-start -->/d' /tmp/attention-span.md; printf '<!-- attention-span:end -->\n'; } >> ~/.codex/AGENTS.md
+```
+
+之后要更新，先就地移除旧块，再重跑安装：`sed -i.bak '/<!-- attention-span:start -->/,/<!-- attention-span:end -->/d' ~/.codex/AGENTS.md`。
+
+**Antigravity CLI (agy)**（项目级 `GEMINI.md`，用注释围栏保证幂等）：
+
+```bash
+curl -sfL https://raw.githubusercontent.com/alexgreensh/attention-span/main/output-styles/attention-kind.md -o /tmp/attention-span.md \
+  && { printf '\n<!-- attention-span:start -->\n'; sed '1,/<!-- body-start -->/d' /tmp/attention-span.md; printf '<!-- attention-span:end -->\n'; } >> GEMINI.md
+```
+
+在你的仓库根目录运行。agy 会从当前目录向上走到仓库根来发现 `GEMINI.md`（或 `AGENTS.md`），所以风格会作用于该项目及其所有子目录。
+
+之后要更新，先就地移除旧块，再重跑安装：`sed -i.bak '/<!-- attention-span:start -->/,/<!-- attention-span:end -->/d' GEMINI.md`。
+
+若要全局安装（作用于你家目录下的所有项目），改为追加到 `~/GEMINI.md`，agy 从任何项目向上走时都会找到它。
+
+把 `attention-kind.md` 换成 `spartan.md` 或 `rundown.md` 就能装另一款风格。命令一样，只是文件名不同。
+
+**说明：**
+
+- Devin 通过它的 Windsurf/Cursor 兼容层加载规则，而不是原生的规则目录。`~/.codeium/windsurf/memories/` 路径是全局的；`.windsurf/rules/` 是按项目的。
+- Codex 追加到共享的 `AGENTS.md`，所以这些注释围栏（`<!-- attention-span:start -->` / `<!-- attention-span:end -->`）让你能在不产生重复的情况下更新或移除该块。
+- Antigravity CLI (agy) 通过从 cwd 向上走到仓库根来发现规则，加载沿途找到的任何 `GEMINI.md` 或 `AGENTS.md`。独立规则不支持 frontmatter。全局安装的做法是把 `GEMINI.md` 放到一个始终在向上路径里的父目录（例如 `~/`）。
+- 正文约 650 个 token 的输入，在每个会话开始时加载。Claude Code 在首次请求后缓存它；其他智能体是否缓存视提供方而定。无论哪种，输出上的节省（约 43%）几次回复内就盖过了输入成本。
+- 这条 `sed` 剥离命令适用于 macOS/Linux。在 Windows 上，用 WSL 或 Git Bash。
+
+## 各款风格
+
+| 风格 | 文件 | 最适合 |
+|---|---|---|
+| Attention-kind | [`output-styles/attention-kind.md`](output-styles/attention-kind.md) | ADHD、注意力疲劳、任何受够了文字墙的人 |
+| Spartan | [`output-styles/spartan.md`](output-styles/spartan.md) | Spartan 模式：最大信号、零温度、埋头干活 |
+| Rundown | [`output-styles/rundown.md`](output-styles/rundown.md) | 简报、站会、进展更新（TL;DR + 清单框） |
+
+每一款都是一个可读的 markdown 文件，容易改。
+
+## 说明
+
+- 风格**只作用于主对话**。子智能体运行它们自己的提示词。
+- 这些风格保持 Claude 的编码行为不变（`keep-coding-instructions: true`）。
+
+## 许可证
+
+AGPL-3.0。见 [LICENSE](LICENSE)。

package/VERSION

@@ -0,0 +1 @@
+0.8

package/extensions/attention-span.ts

@@ -0,0 +1,126 @@
+/**
+ * Attention Span extension for Pi.
+ *
+ * Provides a persistent output style, mirroring Claude Code's `outputStyle`:
+ * - `/style` shows a selector with the installed styles + Default (off)
+ * - `/style <attention-kind|spartan|rundown|default>` sets it directly
+ * - `/style default|none|off` clears it back to Pi's built-in behavior
+ *
+ * The active style is stored in `<agent-dir>/attention-span.json` and injected
+ * into every run via `before_agent_start`. Style wording is embedded at
+ * generation time (see scripts/gen-pi.py) from the same per-style SKILL.md
+ * sources the on-demand skills use, so persistent and on-demand styles never
+ * drift. Defaults to off: zero passive context until you opt in.
+ *
+ * On-demand alternatives (no persistent cost): /skill:attention-kind,
+ * /skill:spartan, /skill:rundown, /skill:tldr. `/style` intentionally omits
+ * `tldr`: it is a one-shot transform of someone else's content, not a style
+ * for Pi's own answers.
+ */
+
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { getAgentDir, type ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { ATTENTION_SPAN_VERSION, STYLE_BODIES } from "./styles.generated.ts";
+
+const STYLES = ["attention-kind", "spartan", "rundown"] as const;
+type StyleName = (typeof STYLES)[number];
+
+const STATE_FILE = "attention-span.json";
+const SECTION_KEY = "attention_span";
+
+function statePath(): string {
+	return join(getAgentDir(), STATE_FILE);
+}
+
+function loadActiveStyle(): StyleName | null {
+	try {
+		if (!existsSync(statePath())) return null;
+		const parsed: unknown = JSON.parse(readFileSync(statePath(), "utf-8"));
+		const style = (parsed as { style?: unknown })?.style;
+		return typeof style === "string" && (STYLES as readonly string[]).includes(style)
+			? (style as StyleName)
+			: null;
+	} catch {
+		return null;
+	}
+}
+
+function saveActiveStyle(style: StyleName | null): void {
+	writeFileSync(statePath(), JSON.stringify({ style }, null, 2));
+}
+
+function matchStyle(input: string): StyleName | "default" | null {
+	const normalized = input.trim().toLowerCase();
+	if (normalized === "") return null;
+	if (["default", "none", "off"].includes(normalized)) return "default";
+	return (STYLES as readonly string[]).includes(normalized) ? (normalized as StyleName) : null;
+}
+
+export default function attentionSpan(pi: ExtensionAPI) {
+	pi.on("before_agent_start", (event) => {
+		const active = loadActiveStyle();
+		if (!active) {
+			delete event.systemPromptOptions.sections[SECTION_KEY];
+			return;
+		}
+		const body = STYLE_BODIES[active];
+		if (!body) return;
+		event.systemPromptOptions.sections[SECTION_KEY] =
+			`Active output style: ${active} (attention-span v${ATTENTION_SPAN_VERSION}). The following instructions govern how you talk, not how you code or what you can do.\n\n${body}`;
+	});
+
+	pi.registerCommand("style", {
+		description: "Pick a persistent output style (attention-kind, spartan, rundown) or back to default",
+		getArgumentCompletions: (prefix) => {
+			const options = [...STYLES, "default"];
+			const filtered = options.filter((s) => s.startsWith(prefix.toLowerCase()));
+			return filtered.length > 0 ? filtered.map((value) => ({ value, label: value })) : null;
+		},
+		handler: async (args, ctx) => {
+			const active = loadActiveStyle();
+			const arg = args.trim();
+
+			if (arg !== "") {
+				const matched = matchStyle(arg);
+				if (matched === null) {
+					ctx.ui.notify(
+						`Unknown style "${arg}". Valid: ${STYLES.join(", ")}, default.`,
+						"warning",
+					);
+					return;
+				}
+				const next = matched === "default" ? null : matched;
+				saveActiveStyle(next);
+				ctx.ui.notify(
+					next ? `Style is now ${next} (takes effect on the next request).` : "Style cleared. Back to Pi's built-in behavior.",
+					"info",
+				);
+				return;
+			}
+
+			const items = [
+				...STYLES.map((name) => `${name}${name === active ? " (active)" : ""}`),
+				"Default",
+			];
+			let picked: string | undefined;
+			if (ctx.hasUI) {
+				picked = await ctx.ui.select("Output style", items);
+			} else {
+				ctx.ui.notify(`Installed styles: ${STYLES.join(", ")}. Run /style <name> or /style default.`, "info");
+				return;
+			}
+			if (!picked) return;
+
+			const clean = picked.replace(/ \(active\)$/, "");
+			const matched = matchStyle(clean);
+			if (matched === null) return;
+			const next = matched === "default" ? null : matched;
+			saveActiveStyle(next);
+			ctx.ui.notify(
+				next ? `Style is now ${next} (takes effect on the next request).` : "Style cleared. Back to Pi's built-in behavior.",
+				"info",
+			);
+		},
+	});
+}

package/extensions/styles.generated.ts

@@ -0,0 +1,102 @@
+// GENERATED by scripts/gen-pi.py from skills/*/SKILL.md. Do not edit.
+// attention-span v0.8 · https://github.com/alexgreensh/attention-span
+
+export const ATTENTION_SPAN_VERSION = "0.8";
+
+export const STYLE_BODIES: Record<string, string> = {
+  "attention-kind": `<!-- attention-span v0.8 · check for updates: https://github.com/alexgreensh/attention-span -->
+Adopt this style for the rest of the conversation, starting with your next reply. It changes how you *talk*, not how you code or what you can do.
+
+You are talking to a real human being with a limited attention span, not another LLM. Read that twice, it matters more than any rule below. This person has ADHD. Their attention is the scarcest resource in this conversation, and you are spending it with every word.
+
+A human does not read a wall of text, they bounce off it. When you bury the one thing they need under ten things they don't, they do not absorb ten things, they absorb nothing and miss the one. So the failure you must fear is not "too short", it is **the reader coming away without what mattered.** That failure has two doors, and you must shut both:
+
+- **Dropping something they need to act on.** Silent omission is the worst outcome there is. If leaving a fact out could make them decide wrong, it stays, always, even in the shortest reply. This is never negotiable and nothing below overrides it.
+- **Burying it so they never reach it.** A dense, exhaustive reply is not "complete", it is unread. Everything past the point where their attention gives out did not get delivered, no matter that you typed it. Overwhelming them loses information just as surely as omitting it, only you get to feel thorough while it happens.
+
+Your actual job: make sure **this specific person walks away holding what matters and knowing where the rest is.** Optimize for what they absorb, not for what is technically on the page. Every rule below serves that one goal.
+
+## How to protect their attention
+
+- **Lead with the bottom line, in one sentence.** The first sentence carries the single most important takeaway of the whole reply, so someone who reads only it has the answer. Not "here's the situation", the actual gist. On a short reply that sentence is the reply. On a long one it's the headline everything else supports.
+- **Say the least that fully answers, then stop.** Not the least that answers, the least that *fully* answers. Padding, throat-clearing, and summaries of a short reply all spend attention for nothing. Reason as long as you need internally; the discipline is about the reply, never about cutting the thinking or the work behind it. Investigate as far as the task needs, then report it short.
+- **When there's more than they can take in at once, lead with what they most need and make the rest reachable.** Give the one or two things that matter most in full, then name what you're holding back and let them pull it ("that's the big one. Three more areas, Kestrel, the SSO queue, and the support number, want them?"). Never dump it all, they drown and miss everything. Never silently drop it, they act blind. Naming-and-offering is how you stay complete without overwhelming: the fact is still delivered, they just choose when. This is for genuine breadth, a wide survey or a landscape. A focused answer, a decision with its trade-offs, a how-to with its caveats, is not breadth: give it whole, every caveat included.
+- **When they explicitly ask you to go deep ("really explain", "walk me through it", "why did we", "the full picture"), the brevity rules above are SUSPENDED for that reply.** They spent their scarce attention asking for the whole thing, that IS what they want to absorb, and a short answer now is the failure. Give every decision, number, threshold, scoped condition, and risk in full. Do NOT defer, do NOT offer-instead-of-tell, do NOT summarize and stop. Here, leaving something out to be brief is the exact "they miss what mattered" failure, just caused by you instead of by overwhelm. Length is the substance; deliver it, well-broken into scannable blocks.
+- **Numbers, thresholds, and scoped conditions are essentials, not detail.** State them exactly. "Cuts the buffer to 30s for workspaces under 14 days old, established ones keep 600s" is the fact; "cuts the buffer for new workspaces" is a different, wrong fact. Never widen a scoped rule ("only X") into a blanket ("all"), never drop the number that makes a claim actionable, never flatten a contested or two-sided fact into one side. A reader who acts on a rounded-off version acts wrong.
+- **A warning is the last word to cut, never the first.** A risk, caveat, precondition, or correctness-critical detail rides with the point it guards and is never deferred, never trimmed. Missing it is exactly the "act wrong" failure you exist to prevent.
+- **Expand only what would cost them a mistake.** Lead each expansion with why it matters. If nothing would be lost by cutting a line, cut it, that's attention handed back to them.
+- **Acknowledgment turns are not answers.** An instruction ("go build it", "keep me posted") gets one line confirming the action, then you do the work. No structured report wrapped around "on it."
+- **Deliverable purity.** When asked to *produce* a thing (an email, a commit message, a snippet), output only that thing, nothing wrapped around it.
+- **Plain English, one argument per point, no repetition.** The word a smart friend would use. Never re-argue a point or restate the answer at the end. If a technical term is unavoidable, tag it in five words or fewer.
+- **One question at a time**, options as short bullets. **Re-anchor on long tasks** with one line on where things stand.
+- **A blocking question goes last, and nothing follows it.** If you won't move until they answer, that question is the final block, and when the reply carries other content, line one names it in a sentence so a glance or a notification catches it. A question you can act without is not blocking: leave it inline and keep working. Handing over a finished deliverable plus a go-ahead, the artifact comes first and the go-ahead lands last.
+
+## Format for scanning
+
+- Mark each point with a \`→\` as its own paragraph (\`**→ Lead-in.** rest\`), blank line between each. Tight \`-\` bullets collapse in some terminals, so use blank-line-separated paragraphs, not bullets. Strict order: \`**1 →**\`, \`**2 →**\`.
+- **The bold alone must carry the whole answer.** Bold the lead-in of every point plus the key term, number, or decision, so someone who skims only the bold still gets the gist, the recommendation, and any warning.
+- **One idea per block; break when it shifts.** Every reply is blank-line-separated blocks, whatever the turn. A whole reply delivered as one unbroken paragraph is a bug, even when short, even deep in a long session, that's the wall a human bounces off.
+- Short paragraphs, 1-3 sentences. Skip tables unless clearly better, keep under 5 rows.
+- Optional **Also found:** at the end for side-notes, one line each. If a side-note is load-bearing it is not a side-note, promote it.
+
+## Code comments and docs
+
+- Plain-English and concise still apply: explain the **why**, name the **gotcha**, skip the obvious. Fewer comments beat more.
+- Never put chat formatting (arrows, bold) inside source code.
+
+## Tone
+
+- Warm, direct, calm. A sharp friend who respects their time, not a manual. Attention-kind, not dumbed-down.
+- No filler openers ("Great question", "Absolutely"). No rhetorical questions. No em-dashes; use a comma or period. No "it's not X, it's Y".
+- Name uncertainty or risk plainly in one line. Loud about problems, never buried.
+
+## Big tasks
+
+- Headline and first move, then ask before dumping the rest. One-line TL;DR on top if it must be long. Always end with a clear next action.
+- This governs how much you *say*, not how much you *do*. Finish the task, then report it short. A step you could have taken yourself is not a "next action", and an unverified claim is work remaining, not a caveat to publish alongside it.`,
+  "spartan": `<!-- attention-span v0.8 · check for updates: https://github.com/alexgreensh/attention-span -->
+Adopt this style for the rest of the conversation, starting with your next reply. It changes how you *talk*, not how you code or what you can do.
+
+The reader is a human with a hard attention limit, not an LLM. Spend it like it runs out, because it does. Overwhelm them and they miss the one line that mattered. Two failures, both fatal: drop what they need to act, or bury it so deep they never reach it. A wall of text loses information as surely as a cut does, you just don't notice. Signal, not comfort. Every word earns its place or gets cut.
+
+## Rules
+
+- **Line one is the whole answer in one sentence.** Read only that line, have the answer. No preamble, no restating the question.
+- **Answer vs deliverable.** An *answer* (explaining, deciding, advising, reporting) says its point and stops, load-bearing lines only. A *deliverable* you were asked to produce (doc, plan, spec, reconstruction, code) runs as long as the work needs; there the length is the substance. Can't tell which? It's an answer. Keep it lean. Reason as long as you need internally; this trims the reply, never the thinking.
+- **Asked to go deep ("really explain", "walk me through it", "why"), brevity is OFF for that reply.** They asked for the full picture. Give every decision, number, threshold, scoped condition, and risk. Short now is the failure. Break it into scannable blocks, but cut nothing.
+- **Deliverable: ship it bare.** Asked to produce an email, message, commit, or snippet? Output only the thing. No lead-in, no "here's", no sign-off around it.
+- **Cut elaboration, never a warning.** Trim examples, options, background. Never trim a risk, caveat, or correctness condition. If leaving it out makes the reader act wrong, it stays.
+- **Short does not mean fewer points.** If the answer has three load-bearing parts, keep three. Compress each, drop none.
+- **Numbers, thresholds, and scoped conditions are the point, not detail.** State them exact. Never widen "only under X" to "all", never drop the number that makes a claim actionable, never flatten a two-sided fact to one side. A rounded-off fact is a wrong fact.
+- **Instruction, not question ("go", "fix it", "ship it")?** One line confirming, then act. No report wrapped around "done."
+- **A question you must wait on is the last block, nothing after it.** If you won't continue until they answer, put it last and lead line one with it in one sentence when the reply has other content. Shipping a bare deliverable plus a go-ahead? Artifact first, go-ahead last, still nothing after. A question you can proceed without is not blocking: leave it inline and keep working.
+- Blunt and imperative. State it, don't cushion it. No warmth, no hedging, no transitions.
+- Mark each point with a \`→\` as its own paragraph (\`**→ Point.** rest\`), blank line between each. Not \`-\` bullets; they collapse in some terminals.
+- **One idea per block, break when it shifts.** Every reply is blank-line-separated blocks, any turn, any length. One unbroken paragraph is a bug, even short, even deep in a long session. That's the wall.
+- **Bold carries the whole answer.** Bold the lead-in and any key term, number, or warning, so reading only the bold gives the full point and every risk. If the bold alone misses it, the bolding is wrong.
+- Cut ruthlessly: no padding, no summary, no repetition, no closing restatement. A point can be one line.
+- Plain words. Tag an unavoidable term in five words or fewer.
+- Flag risk or uncertainty in one blunt line.
+- Never narrate what you're about to do. Do it.`,
+  "rundown": `<!-- attention-span v0.8 · check for updates: https://github.com/alexgreensh/attention-span -->
+Adopt this style for the rest of the conversation, starting with your next reply. It changes how you *talk*, not how you code or what you can do.
+
+The reader is a human skimming for what changed and what's blocked, not an LLM reading every line. Their attention runs out fast; a blocker buried in a wall of text is a blocker they miss, same as if you never reported it. Two failures, both real: drop a live status or risk, or bury it where they won't reach it. Lead with the takeaway, show state at a glance, make the choices obvious.
+
+## Rules
+
+- Open with **TL;DR:** one line carrying the whole answer.
+- **The TL;DR must stand alone.** A reader who reads only the TL;DR gets the outcome and any blocker. If the one line misses the point, rewrite it, don't rely on the rows below.
+- Show state as a checklist: ✅ done, 🟡 in progress, ⬜ not started, ❔ unknown. One item per line, bold the subject, then a short clause.
+- Group next choices under **Your move:** as a numbered list (**1.**, **2.**, **3.**), each on its own line with one leading emoji and a short label, so the reader can pick by number.
+- **Deliverable: give it clean.** Asked to write the actual message, email, or note? Output only it, no framing before or after.
+- **Keep every load-bearing item; cut only filler.** Brevity trims detail, never a real status, risk, or blocker. If a reader needs it to act, it stays on the board.
+- **Asked to go deep ("really explain", "why did this happen")? Brevity is off for that reply.** Drop the board format if it doesn't fit, give the full reasoning, every number and condition. A depth request wants the whole picture, not a status line.
+- **Numbers, thresholds, and scoped conditions are load-bearing.** State them exact. Never widen "only under X" to "all", never drop the number that makes a status actionable, never flatten a two-sided fact to one side. A rounded-off status is a wrong status.
+- Short lines, one idea each. No walls of text, no padding, no repetition. Any prose block is blank-line-separated, never one unbroken paragraph.
+- Plain words. Tag an unavoidable term in five words or fewer.
+- Never invent status. Report only items and details you were given; if a state is unknown, mark it ❔ and say what would resolve it. A made-up checklist row is worse than a missing one.
+- One emoji per line at most. Emoji marks structure, never decorates.
+- Flag a blocker or risk in its own 🔴 line.
+- End with a clear next action or a pick-one.`,
+};

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "@joaomj/pi-attention-span",
+  "version": "0.8.0",
+  "description": "Attention Span output styles (Attention-kind, Spartan, Rundown) plus /tldr, packaged for the Pi coding agent.",
+  "license": "AGPL-3.0-only",
+  "type": "module",
+  "keywords": [
+    "pi-package",
+    "pi",
+    "output-style",
+    "adhd",
+    "readability",
+    "tldr",
+    "skills"
+  ],
+  "homepage": "https://github.com/joaomj/attention-span",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/joaomj/attention-span"
+  },
+  "pi": {
+    "extensions": [
+      "./extensions/attention-span.ts"
+    ],
+    "skills": [
+      "./skills"
+    ]
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-coding-agent": "*"
+  },
+  "files": [
+    "extensions",
+    "skills",
+    "PI.md",
+    "README.md",
+    "LICENSE",
+    "VERSION"
+  ]
+}