@softspark/ai-toolkit 3.1.0 → 3.2.0

package/AGENTS.md

@@ -348,7 +348,7 @@ Security expert. Use for OWASP Top 10, CVE analysis, security audits, penetratio
 
 ### `seo-specialist`
 
-Search engine optimization specialist. Trigger words: SEO, search engine, meta tags, structured data, Core Web Vitals, sitemap, robots.txt, schema.org
+Search engine + generative engine optimization specialist. Trigger words: SEO, GEO, AEO, search engine, meta tags, structured data, Core Web Vitals, sitemap, robots.txt, schema.org, llms.txt, ChatGPT visibility, Claude citation, Perplexity ranking, AI Overviews
 
 **Tools:** `Read, Write, Edit, Bash, Grep, Glob`
 
@@ -436,7 +436,7 @@ Specialized agent personas — apply their expertise for relevant tasks:
 - **search-specialist**: Information retrieval and search optimization specialist. Trigger words: search, query, semantic search, information retrieval, relevance, ranking, search optimization
 - **security-architect**: Proactive security design expert. Use for Threat Modeling, architecture security reviews, and designing secure systems (AuthN/AuthZ, Crypto).
 - **security-auditor**: Security expert. Use for OWASP Top 10, CVE analysis, security audits, penetration testing, vulnerability assessment, hardening. Triggers: security, owasp, cve, vulnerability, audit, hardening, penetration, pentest, injection test, api security.
-- **seo-specialist**: Search engine optimization specialist. Trigger words: SEO, search engine, meta tags, structured data, Core Web Vitals, sitemap, robots.txt, schema.org
+- **seo-specialist**: Search engine + generative engine optimization specialist. Trigger words: SEO, GEO, AEO, search engine, meta tags, structured data, Core Web Vitals, sitemap, robots.txt, schema.org, llms.txt, ChatGPT visibility, Claude citation, Perplexity ranking, AI Overviews
 - **system-governor**: The Guardian of the Constitution. Validates all evolutionary changes and enforces immutable rules. Has VETO power.
 - **tech-lead**: Technical authority for code quality, architecture patterns, and stack decisions. Use for code reviews, technological disputes, and standards enforcement.
 - **technical-researcher**: Deep technical investigation and multi-source research synthesis specialist. Trigger words: technical research, feasibility study, root cause analysis, API investigation, compatibility research, comparison matrix, synthesize, aggregate, report, executive summary, gap analysis, findings, multi-source, cross-reference
@@ -454,7 +454,7 @@ Skills are invocable commands or auto-loaded knowledge sources:
 - **architecture-audit**: Explore codebase organically for architectural friction, discover shallow modules, and propose module-deepening refactors as GitHub issue RFCs using parallel sub-agent interface designs. Use when user wants to improve architecture, find shallow modules, deepen modules, or reduce coupling. Codex-adapted: uses native subagents and plan tracking.
 - **architecture-decision**: Architecture decision making via trade-off analysis in RFC/RFD/ADR format: context, constraints, 3+ options, comparison, recommendation. Triggers: architecture decision, ADR, RFC, RFD, trade-offs, options comparison, design choice, pick between, should we use, evaluate approach. Load when weighing 2+ architectural options or writing decision records.
 - **biz-scan**: Scans codebase for business opportunities by analyzing database schemas, API endpoints, tracking events, and feature flags to surface underutilized capabilities, missing KPIs, and monetization gaps. Use when the user asks about revenue opportunities, business metrics, KPI coverage, analytics gaps, or monetization analysis of a codebase.
-- **brand-voice**: Loaded when writing documentation, content, README, or user-facing text. Prevents generic LLM rhetoric and enforces direct, technical voice.
+- **brand-voice**: Loaded when writing documentation, content, README, or user-facing text, AND when an output-mode is set for conversational responses. Prevents generic LLM rhetoric, enforces direct technical voice, and supplies optional concise/strict response modes.
 - **briefing**: Generate an executive daily briefing that aggregates reports from all agents into a short, decision-focused summary. Use when the user asks for a status update across the whole system — not for one-agent activity reports.
 - **build**: Build the project with auto-detected toolchain (npm, poetry, cargo, go, flutter, Docker). Use when the user asks to compile, bundle, or produce artifacts — not to run tests or deploy.
 - **chaos**: Inject controlled faults for resilience testing on non-production targets. Use when the user explicitly asks for a chaos experiment, latency injection, or dependency kill — never implicit.

package/CHANGELOG.md

@@ -7,6 +7,48 @@ Versioning follows [Semantic Versioning](https://semver.org/).
 
 ---
 
+## v3.2.0 — Output discipline & token-aware status line (2026-05-04)
+
+Minor release. Two coordinated additions: per-response output discipline and a real-token status line installed by default.
+
+### Added
+
+- **`brand-voice` output modes** — `concise` (≤60% tokens) and `strict` (≤40% tokens) extend the existing brand-voice skill with response-length governance. Activate via `output-mode: concise` in project `CLAUDE.md` or `/brand-voice concise`. Mode rules in `app/skills/brand-voice/modes/`.
+- **`measure.py` token evaluator** — fixture-driven before/after comparison at `app/skills/brand-voice/scripts/measure.py`. Asserts budget compliance and load-bearing fact preservation via optional `must_contain.txt` per fixture. JSON and human report formats.
+- **`session_token_stats.py`** — stdlib-only Claude Code session JSONL parser at `scripts/session_token_stats.py`. Reports real input/output/cache token counts per session, supports `--since`, `--baseline`, `--statusline`, and `--json` modes.
+- **Comprehensive default status line** — new `app/hooks/ai-toolkit-statusline.sh` renders a single line with cwd, git branch + dirty marker, context-window as a 10-cell progress bar (green <70% / orange 70–89% / red ≥90%), upload arrow `↑` (input tokens, green) + download arrow `↓` (output tokens, red), effort level, and model name. All token + cost data is read directly from Claude Code's statusLine stdin (`context_window.total_input_tokens`, `total_output_tokens`, `cost.total_cost_usd`, `effort.level`) — no JSONL parsing in the hot path, ~50ms cold start. Installed automatically into `~/.claude/settings.json` by `ai-toolkit install` (and `update`). User-customized statusLine entries (without the ai-toolkit `_source` tag) are preserved untouched. Cost-estimate segment is opt-in via `AI_TOOLKIT_STATUSLINE_SHOW_COST=1`.
+- **`merge-hooks.py` statusLine support** — `inject` writes the toolkit statusLine only when the target has none or has a stale toolkit-installed one. `strip` removes only toolkit-installed entries.
+- **`briefing` skill `--tokens` mode** — `/briefing --tokens [--since 7d]` for explicit reporting and baseline capture. Includes wire-up docs for the status-line hook and `AI_TOOLKIT_STATUSLINE_*` opt-out env vars.
+- **Hook runtime scripts deployed alongside hooks** — `scripts/install_steps/hooks.py` now copies a curated allowlist of Python helpers (`session_token_stats.py`, `version_check.py`) to `~/.softspark/ai-toolkit/scripts/`, so hooks work on a fresh install before the npm-global package catches up. Hook resolution order: `AI_TOOLKIT_DIR` → `~/.softspark/ai-toolkit/` → npm global → walk up from script (dev fallback).
+
+### Opt-out
+
+- `AI_TOOLKIT_STATUSLINE_DISABLE=1` silences output entirely
+- `AI_TOOLKIT_STATUSLINE_NO_TOKENS=1` hides token arrows segment
+- `AI_TOOLKIT_STATUSLINE_NO_GIT=1` hides git segment
+- `AI_TOOLKIT_STATUSLINE_NO_EFFORT=1` hides effort level segment
+- `AI_TOOLKIT_STATUSLINE_NO_COLOR=1` disables ANSI colors
+- `AI_TOOLKIT_STATUSLINE_SHOW_COST=1` appends Claude Code's reported `cost.total_cost_usd` (off by default — long Opus sessions show alarming numbers)
+- `AI_TOOLKIT_STATUSLINE_DUMP=1` writes received stdin to `/tmp/cc-statusline-input.json` (debug only)
+
+### Tests
+
+- 38 new bats tests across `tests/test_brand_voice.bats`, `tests/test_session_token_stats.bats`, `tests/test_statusline_hook.bats`, `tests/test_merge_hooks_statusline.bats`, plus install-step assertion in `tests/test_install.bats`.
+
+---
+
+## v3.1.1 — Windows install fix (2026-04-29)
+
+Patch release. `ai-toolkit install --local` crashed on Windows before doing any work because `scripts/install_steps/project_registry.py` imported `fcntl` (POSIX-only) at module load, raising `ModuleNotFoundError: No module named 'fcntl'`.
+
+### Fixed
+
+- **Windows install crash** — `project_registry` now imports `fcntl` and `msvcrt` defensively (try/except → `None`) and `_registry_lock()` selects between `fcntl.flock` (POSIX) and `msvcrt.locking` (Windows) at runtime. POSIX semantics unchanged; Windows acquires the lock with `LK_NBLCK` + 30 s deadline + 10 ms retry backoff.
+
+### Added
+
+- **Windows compat regression test** — `tests/test_windows_support.bats` now blocks `import fcntl` via a custom `meta_path` finder, stubs `msvcrt`, and forces the Windows branch of `_registry_lock` so future regressions are caught on the POSIX CI runners without needing a Windows machine.
+
 ## v3.1.0 — Global Editor Install Alignment (2026-04-28)
 
 Minor release aligning global and project-local editor configuration with the current documented surfaces for all supported editors.

package/README.md

@@ -6,7 +6,7 @@
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
 [![Skills](https://img.shields.io/badge/skills-112-brightgreen)](app/skills/)
 [![Agents](https://img.shields.io/badge/agents-44-blue)](app/agents/)
-[![Tests](https://img.shields.io/badge/tests-973%20passing-success)](tests/)
+[![Tests](https://img.shields.io/badge/tests-1038%20passing-success)](tests/)
 
 <p align="center">
   <img src="assets/ai-toolkit-readme-hero.png" alt="ai-toolkit 3 README hero showing one toolkit for 12 AI editors" width="900">
@@ -14,33 +14,14 @@
 
 ---
 
-## What's New in v3.1.0
+## What's New in v3.2.0
 
-**3.1.0 aligns global and project-local editor installs** with the current documented config surfaces for all 12 supported tools.
+Minor release adding response-length governance and a token-aware status line installed by default.
 
-- `ai-toolkit install --editors cline` now writes documented global rules under `~/Documents/Cline/Rules/`.
-- `ai-toolkit install --editors roo` now writes documented global rules under `~/.roo/rules/`.
-- `ai-toolkit install --editors aider` safely creates `~/.aider.conf.yml` only when absent and refreshes `~/.aider-ai-toolkit-CONVENTIONS.md`.
-- Roo Code now has project MCP sync via `.roo/mcp.json` from the canonical `.mcp.json`.
-- Cursor rules are explicitly project-local; Cursor MCP remains supported at project/global scope through `.cursor/mcp.json`.
-
-### Carried from v3.0.0 (feature release)
-
-- **Deep coverage: every editor at 100% of its native surface.** New generators emit hooks, sub-agents, custom commands, and skill pointers per editor: `generate_cursor_agents.py`, `generate_cursor_hooks.py`, `generate_windsurf_hooks.py`, `generate_gemini_commands.py`, `generate_gemini_hooks.py`, `generate_gemini_skills.py`, `generate_augment_agents.py`, `generate_augment_commands.py`, `generate_augment_hooks.py`, `generate_augment_skills.py`, `generate_codex_skills.py`.
-- **`--profile full`** turns on every native surface across all supported editors in one flag. `minimal` / `standard` / `strict` retain prior semantics but `standard` now also wires Gemini hooks and the Copilot directory layout (see Breaking Changes).
-- **Codex skill mirroring** uses Codex's native `.agents/skills/` discovery path. `--editors codex` installs translated skills there; `--codex-skills` explicitly refreshes the same catalog.
-- **58 new bats tests** covering native surface generators plus per-editor suites for aider, antigravity, augment, claude-code, cline, codex, copilot, cursor, gemini, opencode, roo, windsurf.
-- **Skill quality pass** (folded in from the 2.12 work that is now skipped): 62 skills upgraded to 4-5 / 5 on the meta-architect audit; `add_gotcha` added as a fifth mutation strategy.
-
-### Breaking changes (from 3.0.0)
-
-- `--profile standard` now installs **Gemini hooks** automatically. To opt out, use `--profile minimal` or pass `--skip gemini-hooks`.
-- Copilot now uses the **directory layout** (`.github/copilot/`) instead of a single monolithic file. Existing single-file installs are preserved but new installs emit the directory form.
-- `2.13.0` is skipped. Upgrade path is `2.12.x` → `3.0.0`.
-
-### Non-breaking additions (opt-in)
-
-- `.windsurf/hooks.json`, `.cursor/hooks.json`, `.cursor/agents/`, `.augment/agents/`, `.augment/commands/`, and `.gemini/commands/` are **only emitted when you opt in** via `--profile full`. Codex skills are emitted under `.agents/skills/` whenever the Codex editor target is selected, matching Codex's native discovery path.
+- **Output modes for `brand-voice`** — `concise` (≤60% tokens) and `strict` (≤40%) modes governing conversational responses, with rule files in `app/skills/brand-voice/modes/` and a `measure.py` evaluator that runs against fixtures with load-bearing-fact assertions.
+- **Default comprehensive status line** — `ai-toolkit install` now wires `~/.claude/settings.json` to a single line showing cwd, git, a 10-cell context-window progress bar (green <70% / orange 70–89% / red ≥90%), `↑input ↓output` token arrows, effort level, and model. All data read directly from Claude Code's statusLine stdin — no JSONL parsing, ~50 ms cold start. User-customized statusLine entries are preserved untouched. Cost segment opt-in via `AI_TOOLKIT_STATUSLINE_SHOW_COST=1`.
+- **Real token telemetry** — `scripts/session_token_stats.py` parses Claude Code session JSONL for `/briefing --tokens` reporting and baseline capture. Stdlib-only.
+- **Opt-outs via env vars** — `AI_TOOLKIT_STATUSLINE_DISABLE`, `_NO_TOKENS`, `_NO_GIT`, `_NO_EFFORT`, `_NO_COLOR`, `_SHOW_COST` (opt-in), `_DUMP` (debug).
 
 See [CHANGELOG.md](CHANGELOG.md) for full history.
 
@@ -147,8 +128,8 @@ See [CLI Reference](kb/reference/cli-reference.md) for all commands and options.
 | Component | Count | Description |
 |-----------|-------|-------------|
 | `skills/` (task) | 32 | Slash commands: `/commit`, `/build`, `/deploy`, `/test`, `/mcp-builder`, ... |
-| `skills/` (hybrid) | 31 | Slash commands with agent knowledge base |
-| `skills/` (knowledge) | 49 | Domain knowledge auto-loaded by agents (includes 13 `<lang>-rules` skills) |
+| `skills/` (hybrid) | 32 | Slash commands with agent knowledge base |
+| `skills/` (knowledge) | 48 | Domain knowledge auto-loaded by agents (includes 13 `<lang>-rules` skills) |
 | `agents/` | 44 | Specialized agents across 10 categories |
 | `hooks/` | 21 global + 5 skill-scoped | Quality gates, path safety, prompt governance, session lifecycle |
 | `plugins/` | 11 packs | Opt-in domain bundles (security, research, frontend, enterprise, 6 language packs) |
@@ -173,7 +154,7 @@ ai-toolkit/
 │   └── ARCHITECTURE.md  # Full system design
 ├── kb/                  # Reference docs, procedures, plans
 ├── scripts/             # Validation, install, evaluation scripts
-├── tests/               # Bats test suite (973 tests)
+├── tests/               # Bats test suite (1038 tests)
 └── CHANGELOG.md
 ```
 

package/app/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "ai-toolkit",
   "description": "Professional-grade Claude Code toolkit with persona presets, skill security auditor, expanded lifecycle hooks, experimental opt-in plugin packs, benchmark harvesting, and multi-tool support.",
-  "version": "3.1.0",
+  "version": "3.2.0",
   "author": {
     "name": "SoftSpark",
     "url": "https://github.com/softspark"

package/app/ARCHITECTURE.md

@@ -12,6 +12,53 @@ Universal multi-agent system for software development. Works across all reposito
 
 ---
 
+## Layered Model (the five-layer mental model)
+
+The toolkit is organised as five stacked layers. Higher layers depend on lower layers, never the other way around. Treat this as the canonical mental model when adding features — pick the lowest layer that fits.
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│  Layer 5 — Plugins (distribution)                           │
+│  Bundles for npm / marketplace / ai-toolkit eject           │
+│  Files: app/plugins/, plugin.json, package.json             │
+├─────────────────────────────────────────────────────────────┤
+│  Layer 4 — Subagents (delegation)                           │
+│  Specialised personas spawned via Agent / Teams             │
+│  Files: app/agents/, .claude/agents/                        │
+├─────────────────────────────────────────────────────────────┤
+│  Layer 3 — Hooks (the guardrail layer)                      │
+│  Lifecycle events: SessionStart, PreToolUse, Stop, …        │
+│  Files: app/hooks/*.sh, settings.json hooks block           │
+├─────────────────────────────────────────────────────────────┤
+│  Layer 2 — Skills (the knowledge layer)                     │
+│  Slash-commands, knowledge skills, hybrid skills            │
+│  Files: app/skills/<name>/SKILL.md                          │
+├─────────────────────────────────────────────────────────────┤
+│  Layer 1 — CLAUDE.md (the memory layer)                     │
+│  Persistent rules + auto-memory loaded into every session   │
+│  Files: CLAUDE.md (global / project / .claude)              │
+└─────────────────────────────────────────────────────────────┘
+```
+
+### Where does my new feature go?
+
+| If the feature is… | Add it at | Examples |
+|---|---|---|
+| A persistent rule the model must always know | Layer 1 (CLAUDE.md) | "always sync_tasks first", commit conventions |
+| A reusable workflow / domain knowledge | Layer 2 (Skills) | `/debug`, `/review`, `python-rules` |
+| Behavior the harness must enforce automatically | Layer 3 (Hooks) | block destructive `rm -rf`, run lint on Stop |
+| A specialised role for delegation | Layer 4 (Subagents) | `security-auditor`, `database-architect` |
+| A shippable bundle for other repos | Layer 5 (Plugins) | `app/plugins/python-stack/` |
+
+### Cross-cutting rules
+
+- A skill MAY trigger an agent (`agent: <name>` frontmatter) — that's Layer 2 calling Layer 4.
+- A hook MUST NOT call a skill — hooks are deterministic shell, skills are LLM-driven.
+- A plugin MAY bundle skills + agents + hooks, but never the inverse.
+- CLAUDE.md is read by every layer; it is the only layer everyone reads.
+
+---
+
 ## Agents
 
 ### Orchestration & Planning (4)

package/app/agents/seo-specialist.md

@@ -1,15 +1,15 @@
 ---
 name: seo-specialist
-description: "Search engine optimization specialist. Trigger words: SEO, search engine, meta tags, structured data, Core Web Vitals, sitemap, robots.txt, schema.org"
+description: "Search engine + generative engine optimization specialist. Trigger words: SEO, GEO, AEO, search engine, meta tags, structured data, Core Web Vitals, sitemap, robots.txt, schema.org, llms.txt, ChatGPT visibility, Claude citation, Perplexity ranking, AI Overviews"
 tools: Read, Write, Edit, Bash, Grep, Glob
 model: sonnet
 color: cyan
 skills: clean-code, seo-validate
 ---
 
-# SEO Specialist
+# SEO + GEO Specialist
 
-Search engine optimization specialist.
+Optimization for both classical search engines AND generative engines (ChatGPT, Claude, Perplexity, Google AI Overviews, Gemini).
 
 ## Expertise
 - Technical SEO
@@ -17,6 +17,7 @@ Search engine optimization specialist.
 - Core Web Vitals
 - Structured data (Schema.org)
 - SEO auditing
+- **Generative Engine Optimization (GEO)** — being cited by LLM-based answer engines
 
 ## Responsibilities
 
@@ -108,4 +109,86 @@ Sitemap: https://example.com/sitemap.xml
 ```python
 smart_query("SEO optimization patterns")
 hybrid_search_kb("technical SEO checklist")
+smart_query("GEO generative engine optimization")
 ```
+
+---
+
+## Generative Engine Optimization (GEO)
+
+Goal: get cited by ChatGPT, Claude, Perplexity, Gemini, and Google AI Overviews — not just rank in classical SERPs.
+
+### When to use SEO vs GEO
+- **SEO**: a user types a query and clicks a link → optimise for click-through.
+- **GEO**: a user asks an LLM and reads the synthesis → optimise for **inclusion in the answer + named source attribution**.
+- They overlap on technical foundations (crawlability, structured data, authority) and diverge on content shape and citability.
+
+### Citability checklist (the 12 things LLM crawlers reward)
+1. **One claim per sentence.** LLMs extract sentence-level snippets — long compound sentences get dropped.
+2. **Lead with the answer.** Inverted-pyramid structure — definition / number / decision in the first sentence of each section.
+3. **Stable, descriptive H2/H3 headings phrased as questions.** Mirrors how users prompt LLMs.
+4. **Unique data, numbers, dates, version strings.** Verifiable facts get cited; opinion does not.
+5. **Named author + author bio with credentials.** Authority signal that survives synthesis.
+6. **Original quotes from named experts.** Quotation blocks are over-represented in LLM citations.
+7. **Comparison tables with explicit labels.** Tables are extracted whole; vague prose is summarised away.
+8. **Schema.org `Article`, `FAQPage`, `HowTo`, `QAPage`, `Person`.** Mandatory for entity disambiguation.
+9. **`llms.txt` at site root.** Curated index of canonical pages for LLM crawlers (Anthropic-proposed convention).
+10. **Stable URLs with semantic slugs.** LLMs cache citations — URL changes erase your authority overnight.
+11. **Cross-linking with descriptive anchors.** "this article" is dead anchor text; use the actual claim.
+12. **Date stamps on every page.** Recency is a top-3 ranking factor for AI Overviews and Perplexity.
+
+### `llms.txt` template
+```
+# Brand Name
+> One-sentence description of what the site is and who it's for.
+
+## Core docs
+- [Title](/url): one-line summary the LLM should remember
+- [Title](/url): one-line summary
+
+## API reference
+- [Endpoint](/url): purpose, auth, response shape
+
+## Optional
+- [Changelog](/changelog): recent updates
+```
+
+### GEO audit checklist
+- [ ] First sentence of every page answers the page's title as a question
+- [ ] At least one comparison table OR numbered list per long-form page
+- [ ] Author block with name + role + LinkedIn / GitHub / ORCID
+- [ ] Schema.org `Article` with `author`, `datePublished`, `dateModified`
+- [ ] Schema.org `FAQPage` for any page with Q/A structure
+- [ ] `llms.txt` at site root with curated canonical URLs
+- [ ] Page contains at least 3 unique data points (numbers, dates, version strings)
+- [ ] Date visible to the user, not just in metadata
+- [ ] No paywall / login wall on indexable content
+- [ ] No JavaScript-only content for primary value (LLM crawlers often skip JS)
+- [ ] Internal links use claim-as-anchor, not "click here"
+- [ ] Brand and product names are consistent across the entire site
+
+### Measuring GEO outcomes
+GEO has no Search Console equivalent. Substitutes:
+- **Manual prompt testing**: query each target prompt monthly in ChatGPT / Claude / Perplexity / AI Overviews; record whether your domain appears in the citation footer.
+- **Referrer analysis**: filter analytics by `Referer` containing `chat.openai.com`, `perplexity.ai`, `claude.ai`, `gemini.google.com`.
+- **Brand-mention monitoring**: tools that scrape LLM outputs for mentions (Otterly, Profound, AthenaHQ).
+- **Server logs**: identify and welcome crawler user-agents (`GPTBot`, `ClaudeBot`, `PerplexityBot`, `Google-Extended`, `OAI-SearchBot`).
+
+### `robots.txt` for AI crawlers (allow by default)
+```
+User-agent: GPTBot
+Allow: /
+
+User-agent: ClaudeBot
+Allow: /
+
+User-agent: PerplexityBot
+Allow: /
+
+User-agent: Google-Extended
+Allow: /
+
+User-agent: OAI-SearchBot
+Allow: /
+```
+Disallow only what you would disallow for Googlebot. Blocking AI crawlers wholesale erases you from generative answers — the trade-off is rarely worth it for content sites.

package/app/hooks/ai-toolkit-statusline.sh

@@ -0,0 +1,201 @@
+#!/usr/bin/env bash
+# ai-toolkit-statusline.sh — comprehensive Claude Code status line.
+#
+# Renders one line. Left side: cwd, git, ctx%, i/o token split.
+# Right side (right-aligned): effort level, model name.
+# Optional cost segment is opt-in via AI_TOOLKIT_STATUSLINE_SHOW_COST=1.
+#
+# All token + cost data is read directly from Claude Code's statusLine stdin
+# (context_window.total_input_tokens, total_output_tokens, cost.total_cost_usd,
+# effort.level). No JSONL parsing in the hot path.
+#
+# Wire-up: ai-toolkit installer adds this as default `statusLine` in
+# ~/.claude/settings.json. Manual config:
+#     {
+#       "statusLine": {
+#         "type": "command",
+#         "command": "bash ~/.softspark/ai-toolkit/hooks/ai-toolkit-statusline.sh"
+#       }
+#     }
+#
+# Env vars (all optional):
+#   AI_TOOLKIT_DIR                  — toolkit install location (auto-detected)
+#   AI_TOOLKIT_STATUSLINE_DISABLE   — "1" silences output entirely
+#   AI_TOOLKIT_STATUSLINE_NO_COLOR  — "1" disables ANSI colors
+#   AI_TOOLKIT_STATUSLINE_NO_TOKENS — "1" hides i/o segment
+#   AI_TOOLKIT_STATUSLINE_NO_GIT    — "1" hides git segment
+#   AI_TOOLKIT_STATUSLINE_NO_EFFORT — "1" hides effort segment
+#   AI_TOOLKIT_STATUSLINE_SHOW_COST — "1" appends Claude Code's reported cost
+#   AI_TOOLKIT_STATUSLINE_DUMP      — "1" writes stdin to /tmp/cc-statusline-input.json
+#
+# Performance: ~50ms (single python3 parse of stdin, one git invocation).
+
+set -u
+
+[ "${AI_TOOLKIT_STATUSLINE_DISABLE:-0}" = "1" ] && exit 0
+
+# ── Colors ───────────────────────────────────────────────────────────────────
+# Claude Code captures stdout via pipe but interprets ANSI escapes when it
+# renders the statusline. So always emit colors unless explicitly disabled.
+if [ "${AI_TOOLKIT_STATUSLINE_NO_COLOR:-0}" = "1" ]; then
+    C_RESET="" C_GREEN="" C_BOLD_GREEN="" C_CYAN="" C_BLUE="" C_RED=""
+    C_YELLOW="" C_MAGENTA="" C_DIM="" C_GRAY="" C_BOLD_YELLOW="" C_ORANGE=""
+else
+    C_RESET=$'\033[0m'
+    C_GREEN=$'\033[0;32m'
+    C_BOLD_GREEN=$'\033[1;32m'
+    C_CYAN=$'\033[0;36m'
+    C_BLUE=$'\033[1;34m'
+    C_RED=$'\033[0;31m'
+    C_YELLOW=$'\033[0;33m'
+    C_BOLD_YELLOW=$'\033[1;33m'
+    C_MAGENTA=$'\033[0;35m'
+    C_DIM=$'\033[2m'
+    C_GRAY=$'\033[0;37m'
+    C_ORANGE=$'\033[38;5;208m'
+fi
+
+# ── Parse stdin in one python3 invocation ────────────────────────────────────
+INPUT="$(cat 2>/dev/null || true)"
+
+if [ "${AI_TOOLKIT_STATUSLINE_DUMP:-0}" = "1" ] && [ -n "$INPUT" ]; then
+    printf '%s' "$INPUT" > /tmp/cc-statusline-input.json 2>/dev/null
+fi
+
+PARSED="$(printf '%s' "$INPUT" | python3 -c '
+import json, sys
+def get(d, path):
+    for k in path.split("."):
+        d = d.get(k) if isinstance(d, dict) else None
+        if d is None:
+            return ""
+    return d if d is not None else ""
+def fmt_tokens(n):
+    try:
+        n = int(n)
+    except (TypeError, ValueError):
+        return "0"
+    if n >= 1000:
+        return f"{n/1000:.1f}k"
+    return str(n)
+try:
+    d = json.loads(sys.stdin.read() or "{}")
+except Exception:
+    d = {}
+cwd = get(d, "cwd") or ""
+model = get(d, "model.display_name") or get(d, "model.id") or ""
+ctx_pct = get(d, "context_window.used_percentage")
+in_tok = fmt_tokens(get(d, "context_window.total_input_tokens"))
+out_tok = fmt_tokens(get(d, "context_window.total_output_tokens"))
+cost = get(d, "cost.total_cost_usd")
+try:
+    cost_str = f"{float(cost):.2f}" if cost != "" else ""
+except (TypeError, ValueError):
+    cost_str = ""
+effort = get(d, "effort.level") or ""
+print(f"{cwd}\t{model}\t{ctx_pct}\t{in_tok}\t{out_tok}\t{cost_str}\t{effort}")
+' 2>/dev/null)"
+
+IFS=$'\t' read -r CWD MODEL_NAME CTX_USED IN_TOK OUT_TOK COST EFFORT <<< "$PARSED"
+[ -z "$CWD" ] && CWD="$PWD"
+
+# ── Segment: prompt + dir ────────────────────────────────────────────────────
+DIR_BASENAME="$(basename "$CWD" 2>/dev/null || echo '~')"
+SEG_PROMPT="${C_BOLD_GREEN}\xe2\x9e\x9c${C_RESET}  ${C_CYAN}${DIR_BASENAME}${C_RESET}"
+
+# ── Segment: git ────────────────────────────────────────────────────────────
+SEG_GIT=""
+if [ "${AI_TOOLKIT_STATUSLINE_NO_GIT:-0}" != "1" ] && \
+   git -C "$CWD" rev-parse --git-dir >/dev/null 2>&1; then
+    BRANCH="$(git -C "$CWD" -c core.fsmonitor=false symbolic-ref --short HEAD 2>/dev/null)"
+    if [ -n "$BRANCH" ]; then
+        DIRTY=""
+        if git -C "$CWD" -c core.fsmonitor=false status --porcelain 2>/dev/null | grep -q .; then
+            DIRTY=" ${C_RED}\xe2\x9c\x97${C_RESET}"
+        fi
+        SEG_GIT=" ${C_BLUE}git:(${C_RED}${BRANCH}${C_BLUE})${C_RESET}${DIRTY}"
+    fi
+fi
+
+# ── Segment: context window as progress bar ────────────────────────────────
+# 10-cell bar with usage-shaded color: green <50%, yellow 50-79%, red ≥80%.
+build_ctx_bar() {
+    local pct=$1
+    local cells=10
+    local filled=$(( (pct * cells + 50) / 100 ))
+    [ "$filled" -gt "$cells" ] && filled=$cells
+    [ "$filled" -lt 0 ] && filled=0
+    local color
+    if [ "$pct" -ge 90 ]; then
+        color="$C_RED"
+    elif [ "$pct" -ge 70 ]; then
+        color="$C_ORANGE"
+    else
+        color="$C_GREEN"
+    fi
+    local bar=""
+    local i=0
+    while [ "$i" -lt "$filled" ]; do
+        bar+="\xe2\x96\x88"  # █  FULL BLOCK
+        i=$((i+1))
+    done
+    local empty=""
+    while [ "$i" -lt "$cells" ]; do
+        empty+="\xe2\x96\x91"  # ░  LIGHT SHADE
+        i=$((i+1))
+    done
+    printf '%b' "${color}${bar}${C_DIM}${empty}${C_RESET}"
+}
+
+SEG_CTX=""
+if [ -n "$CTX_USED" ]; then
+    CTX_INT="$(printf '%.0f' "$CTX_USED" 2>/dev/null || echo "$CTX_USED")"
+    case "$CTX_INT" in
+        ''|*[!0-9]*) CTX_INT=0 ;;
+    esac
+    SEG_CTX=" $(build_ctx_bar "$CTX_INT") ${C_DIM}${CTX_INT}%${C_RESET}"
+fi
+
+# ── Segment: tokens with up/down arrows ─────────────────────────────────────
+# ↑ green = upload (input tokens sent to model)
+# ↓ red   = download (output tokens received from model)
+SEG_TOKENS=""
+if [ "${AI_TOOLKIT_STATUSLINE_NO_TOKENS:-0}" != "1" ] && \
+   [ -n "$IN_TOK" ] && [ "$IN_TOK" != "0" -o "$OUT_TOK" != "0" ]; then
+    SEG_TOKENS="  ${C_BOLD_GREEN}\xe2\x86\x91${IN_TOK}${C_RESET} ${C_RED}\xe2\x86\x93${OUT_TOK}${C_RESET}"
+    if [ "${AI_TOOLKIT_STATUSLINE_SHOW_COST:-0}" = "1" ] && [ -n "$COST" ]; then
+        SEG_TOKENS+=" ${C_BOLD_GREEN}\$${COST}${C_RESET}"
+    fi
+fi
+
+# ── Right-aligned segments: effort + model ───────────────────────────────────
+SEG_EFFORT=""
+if [ "${AI_TOOLKIT_STATUSLINE_NO_EFFORT:-0}" != "1" ] && [ -n "$EFFORT" ]; then
+    case "$EFFORT" in
+        xhigh|high) E_COLOR="$C_BOLD_YELLOW" ;;
+        medium)     E_COLOR="$C_YELLOW" ;;
+        *)          E_COLOR="$C_DIM" ;;
+    esac
+    SEG_EFFORT="${C_DIM}effort:${C_RESET}${E_COLOR}${EFFORT}${C_RESET}"
+fi
+
+SEG_MODEL=""
+if [ -n "$MODEL_NAME" ]; then
+    SEG_MODEL="${C_MAGENTA}${MODEL_NAME}${C_RESET}"
+fi
+
+# ── Render (left-aligned, single line) ───────────────────────────────────────
+# Right-align was attempted earlier but Claude Code reserves variable-width
+# space on the right of the rendered statusline for its own UI overlay,
+# truncating any content right-padded near COLUMNS. Left-align with effort
+# and model as trailing segments avoids the truncation.
+SEG_TRAILER=""
+[ -n "$SEG_EFFORT" ] && SEG_TRAILER+=" $SEG_EFFORT"
+[ -n "$SEG_MODEL" ] && SEG_TRAILER+=" $SEG_MODEL"
+
+printf "%b%b%b%b%b\n" \
+    "$SEG_PROMPT" \
+    "${SEG_GIT:-}" \
+    "${SEG_CTX:-}" \
+    "${SEG_TOKENS:-}" \
+    "${SEG_TRAILER}"

package/app/hooks.json

@@ -234,5 +234,10 @@
                 ]
             }
         ]
+    },
+    "statusLine": {
+        "_source": "ai-toolkit",
+        "type": "command",
+        "command": "bash \"$HOME/.softspark/ai-toolkit/hooks/ai-toolkit-statusline.sh\""
     }
 }

package/app/skills/brand-voice/SKILL.md

@@ -1,8 +1,8 @@
 ---
 name: brand-voice
-description: "Loaded when writing documentation, content, README, or user-facing text. Prevents generic LLM rhetoric and enforces direct, technical voice."
+description: "Loaded when writing documentation, content, README, or user-facing text, AND when an output-mode is set for conversational responses. Prevents generic LLM rhetoric, enforces direct technical voice, and supplies optional concise/strict response modes."
 effort: medium
-user-invocable: false
+user-invocable: true
 allowed-tools: Read
 ---
 
@@ -10,6 +10,8 @@ allowed-tools: Read
 
 Auto-loaded when writing documentation, content, or user-facing text. Enforces consistent, direct voice and eliminates LLM rhetoric.
 
+Also loaded when a project sets `output-mode: concise` or `output-mode: strict` in `CLAUDE.md`, to govern conversational response length and structure (see [Output Modes](#output-modes)).
+
 ## Anti-Trope List (Banned Phrases)
 
 ### Opening Tropes (Never Start With)
@@ -119,6 +121,40 @@ install takes under 30 seconds on a local disk.
 - **CRITICAL**: one idea per sentence. If you write "and" linking two distinct ideas, split the sentence
 - **MANDATORY**: technical claims include a concrete number, name, or example — never assert quality without evidence
 
+## Output Modes
+
+Three modes govern conversational response length. Default applies always; `concise` and `strict` activate per-project or per-session.
+
+| Mode | Token target vs default | Used when |
+|------|-------------------------|-----------|
+| `default` | 100% (no extra constraints) | No `output-mode` configured |
+| `concise` | ≤60% | Daily work, short Q&A, code edits, short reviews |
+| `strict` | ≤40% | Long sessions, expensive models, batch operations, code-only tasks |
+
+Mode rules live in this skill's `modes/` directory. Read the file matching the active mode:
+
+- `modes/concise.md` — bullet-first, no preamble, max 3-sentence prose blocks
+- `modes/strict.md` — telegraphic, no prose blocks, only lists/tables/code
+
+### Activation
+
+1. **Project-level (preferred):** add `output-mode: concise` to project `CLAUDE.md` frontmatter or `.claude/settings.json` under `aiToolkit.outputMode`
+2. **Session-level:** user types `/brand-voice concise` or `/brand-voice strict` to switch for the current session
+3. **Reset:** `/brand-voice default` or remove the project setting
+
+### What modes do NOT change
+
+- Code blocks (always full, never truncated)
+- File paths, line numbers, error messages (always exact)
+- Lists of items the user must see (file lists, test failures, security findings)
+- Plan documents and ADRs (always full structure)
+
+Modes change *prose*, not *data*. If you cut a fact to fit a length budget, you have failed the mode, not honored it.
+
+### Measurement
+
+Run `python3 app/skills/brand-voice/scripts/measure.py --fixtures tests/fixtures/output-modes/` to compare baseline vs mode tokens on the fixture set. Report shows per-fixture deltas and an aggregate ratio.
+
 ## When NOT to Load
 
 - For code or technical specs with no user-facing prose — the voice rules do not apply