@softspark/ai-toolkit 3.1.1 → 3.2.1

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,46 @@ Versioning follows [Semantic Versioning](https://semver.org/).
 
 ---
 
+## v3.2.1 — Statusline shellcheck cleanup (2026-05-04)
+
+Patch release. Lint-only fix in the default status line hook — no behavior change.
+
+### Fixed
+
+- **`app/hooks/ai-toolkit-statusline.sh` shellcheck warnings** — removed the unused `C_GRAY` color variable (SC2034) and replaced the deprecated `[ p -o q ]` form with `{ [ p ] || [ q ]; }` (SC2166). CI shellcheck gate at `--severity=warning` now passes clean across `app/hooks/*.sh`.
+
+---
+
+## 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'`.

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-974%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,12 +14,11 @@
 
 ---
 
-## What's New in v3.1.1
+## What's New in v3.2.1
 
-Patch release fixing the Windows install crash introduced when project registration started using a POSIX-only file lock.
+Patch release. Shellcheck cleanup of the default status line hook — no behavior change.
 
-- **Windows install no longer crashes** — `ai-toolkit install --local` on Windows hit `ModuleNotFoundError: No module named 'fcntl'` before doing any work. The project registry now selects `fcntl` (POSIX) or `msvcrt.locking` (Windows) at runtime; POSIX semantics are unchanged.
-- **Regression test on POSIX CI** — `tests/test_windows_support.bats` simulates the missing-`fcntl` scenario and exercises the Windows lock branch via a stubbed `msvcrt`, so this regression is caught without a Windows runner.
+- **Statusline lint cleanup** — `app/hooks/ai-toolkit-statusline.sh` now passes `shellcheck --severity=warning`: removed the unused `C_GRAY` color variable (SC2034) and replaced the deprecated `[ p -o q ]` form with `{ [ p ] || [ q ]; }` (SC2166).
 
 See [CHANGELOG.md](CHANGELOG.md) for full history.
 
@@ -126,8 +125,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) |
@@ -152,7 +151,7 @@ ai-toolkit/
 │   └── ARCHITECTURE.md  # Full system design
 ├── kb/                  # Reference docs, procedures, plans
 ├── scripts/             # Validation, install, evaluation scripts
-├── tests/               # Bats test suite (974 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.1",
+  "version": "3.2.1",
   "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,200 @@
+#!/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_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_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" ] || [ "$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

package/app/skills/brand-voice/modes/concise.md

@@ -0,0 +1,67 @@
+# Concise Mode
+
+Active when project sets `output-mode: concise` or user invokes `/brand-voice concise`.
+
+## Targets
+
+- Token output ≤60% of default
+- No response longer than 12 lines unless data requires it (file list, test failures, code)
+- No response shorter than 1 sentence — never reply with just "Done." or "OK"
+
+## Hard Rules
+
+1. **No preamble.** Start with the answer or the action result, not "I'll now..." or "Let me explain..."
+2. **No closing summary.** Don't restate what you just did unless asked.
+3. **Bullets over prose** for any list ≥3 items. Each bullet = one fact, ≤80 chars.
+4. **One paragraph max** per topic. If you need two, split into bullets.
+5. **No filler transitions:** drop "Additionally," "Moreover," "It's worth noting," "Importantly."
+6. **No hedging stacks:** "I think we could potentially maybe try" → "Try X."
+7. **Quote facts, not framing:** show file paths, line numbers, exact error text. Cut the explanation around them if the user can read them.
+
+## What to Cut First
+
+| Pattern | Action |
+|---------|--------|
+| "Let me check..." / "I'll look at..." | Delete — just do the action |
+| "It looks like..." / "It seems..." | Delete and state the fact directly |
+| "As you can see..." | Delete — the user can see |
+| "Now that we've ... let's ..." | Delete — start the next action |
+| "Great question!" / "Good point!" | Delete always |
+| Restating the user's question | Delete — answer it |
+| "In summary," / "Overall," | Delete the summary entirely |
+
+## What to Keep
+
+- Concrete file paths, line numbers, command output
+- Exact error messages and stack frames
+- Trade-offs when the user has to decide
+- Warnings about destructive actions
+- Numbers (timings, sizes, counts, percentages)
+
+## Examples
+
+**Bad (verbose):**
+
+```
+Let me check the brand-voice skill for you. I'll read the SKILL.md file
+to understand its current structure and then look at how it integrates
+with the rest of the system. Now that I've examined it, I can see that
+the skill currently has 130 lines and uses YAML frontmatter. As you can
+see, it has a clear structure with sections for anti-tropes, voice
+principles, and rules. In summary, the skill is well-organized.
+```
+
+**Good (concise):**
+
+```
+brand-voice/SKILL.md: 130 lines, YAML frontmatter, sections for anti-tropes,
+voice principles, rules. Structure is clean.
+```
+
+Token ratio: 76 → 25 = 33%.
+
+## Boundary Behavior
+
+- If a question genuinely needs 30 lines to answer, write 30. Don't truncate facts to hit the budget.
+- If the user asks "explain", give one solid paragraph, not a one-liner.
+- If unsure whether the user wants depth, ask. One question is cheaper than a wrong-length response.