@softspark/ai-toolkit 3.1.0 → 3.2.0

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.

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

@@ -0,0 +1,91 @@
+# Strict Mode
+
+Active when project sets `output-mode: strict` or user invokes `/brand-voice strict`. More aggressive than `concise`. Use for long sessions, expensive models, or batch operations where every token costs.
+
+## Targets
+
+- Token output ≤40% of default
+- No prose blocks — only lists, tables, code, exact strings
+- No response longer than 8 lines unless data requires it
+
+## Hard Rules
+
+1. **No prose paragraphs.** Replace prose with bullet lists or tables.
+2. **No connective tissue.** Drop "because", "so", "therefore" unless the causal link is the answer.
+3. **Sentence fragments allowed** for non-data answers: "Done." "Yes." "Already exists at <path>." are valid responses.
+4. **Tables for any comparison ≥2 items.** Two-column min: `key | value`.
+5. **No examples unless asked.** Strict mode assumes the user knows what good output looks like.
+6. **No qualifiers.** Drop "approximately", "roughly", "around", "about" — give exact numbers or say "unknown".
+7. **No second-person framing.** "You should X" → "Do X." or "X is required."
+
+## Mandatory Cuts
+
+| Pattern | Replacement |
+|---------|-------------|
+| Any paragraph >2 sentences | Bullet list |
+| "There are N reasons..." | Numbered list directly |
+| "Let me know if..." | (delete) |
+| "Hope this helps" | (delete) |
+| "Feel free to..." | (delete) |
+| Repeating the question | (delete) |
+| Re-explaining what was just done | (delete) |
+| "Now that..." / "After that..." | (delete) |
+| "It's important to note..." | State the fact, drop the framing |
+| "In other words..." | Pick one phrasing, drop the other |
+
+## What Stays Full-Length
+
+- Code blocks (never elide)
+- File paths, error messages, stack traces (never truncate)
+- Command output the user must see
+- Test failure listings
+- Security findings (CVE IDs, severity, file:line)
+- Diff context lines
+
+## Format Skeleton
+
+For most strict-mode responses, use this skeleton:
+
+```
+<one-line answer or status>
+
+<table or bullets if data>
+
+<next action if applicable, one line>
+```
+
+That's the whole response. No intro, no outro, no transitions.
+
+## Examples
+
+**User asks: "is the test passing?"**
+
+Default: ~40 tokens of explanation. Strict: `Yes. tests/test_brand_voice.bats: 5/5 passing in 0.3s.`
+
+**User asks: "what changed in this commit?"**
+
+Default: prose summary + diff highlights. Strict:
+
+```
+Changed: app/skills/brand-voice/SKILL.md (+23 lines)
+Added:   app/skills/brand-voice/modes/concise.md
+Added:   app/skills/brand-voice/modes/strict.md
+```
+
+**User asks: "should I use Postgres or MySQL?"**
+
+Default: paragraph weighing options. Strict:
+
+| Factor | Postgres | MySQL |
+|--------|----------|-------|
+| JSONB | yes | partial |
+| Replication | logical+phys | logical+phys |
+| Default for this stack | yes | no |
+
+Recommend: Postgres.
+
+## Boundary Behavior
+
+- Strict mode does NOT mean wrong. If a fact requires 5 lines to be correct, write 5 lines. Cut framing, never substance.
+- Strict mode does NOT mean rude. Drop pleasantries, not respect.
+- If the user explicitly asks for explanation, switch to concise mode for that response. Strict is the default, not a gag.

package/app/skills/brand-voice/scripts/measure.py

@@ -0,0 +1,246 @@
+#!/usr/bin/env python3
+"""Measure token reduction of brand-voice output modes against fixtures.
+
+Reads each fixture directory containing default.md, concise.md, strict.md,
+counts tokens with a deterministic whitespace heuristic, and reports per-fixture
+and aggregate ratios. Asserts:
+
+    concise <= CONCISE_BUDGET (default 0.60)
+    strict  <= STRICT_BUDGET  (default 0.40)
+
+Also asserts fact preservation: every file path, identifier, line:number, and
+fenced code block from default.md must appear in concise.md and strict.md.
+
+Usage:
+    python3 app/skills/brand-voice/scripts/measure.py \\
+        --fixtures tests/fixtures/output-modes/
+
+Exit codes:
+    0  all fixtures pass budgets and fact preservation
+    1  one or more fixtures violate budget or drop facts
+    2  invalid fixtures dir or missing files
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import re
+import sys
+from pathlib import Path
+
+CONCISE_BUDGET_DEFAULT = 0.60
+STRICT_BUDGET_DEFAULT = 0.40
+
+PATH_RE = re.compile(r"\b[\w/.-]+\.[a-zA-Z]{1,5}\b")
+LINE_REF_SUFFIX_RE = re.compile(r":\d+$")
+CODE_BLOCK_RE = re.compile(r"```[\w]*\n.*?```", re.DOTALL)
+NUMBER_WITH_UNIT_RE = re.compile(r"\b\d+(?:\.\d+)?(?:ms|s|kb|mb|gb|%)\b", re.IGNORECASE)
+IDENT_BACKTICK_RE = re.compile(r"`([^`\n]+)`")
+
+
+def count_tokens(text: str) -> int:
+    """Whitespace-based token estimate. Deterministic and offline."""
+    return len(text.split())
+
+
+def normalize_path(value: str) -> str:
+    """Strip `:NN` line-number suffix so `foo.ts` and `foo.ts:42` compare equal."""
+    return LINE_REF_SUFFIX_RE.sub("", value).strip("`")
+
+
+def extract_facts(text: str) -> set[str]:
+    """Extract load-bearing facts: file paths, numbers with units, backtick identifiers.
+
+    Does NOT extract code-block bodies. A mode response legitimately shows
+    different code (e.g. the fix) than the default response (e.g. the bug),
+    and treating each code line as a required fact produces false positives.
+    """
+    text_no_code = CODE_BLOCK_RE.sub("", text)
+    facts: set[str] = set()
+
+    for match in PATH_RE.findall(text_no_code):
+        normalized = normalize_path(match)
+        if "/" in normalized:
+            facts.add(normalized)
+
+    for match in IDENT_BACKTICK_RE.findall(text_no_code):
+        cleaned = match.strip()
+        if len(cleaned) >= 3 and not cleaned.startswith("```"):
+            facts.add(normalize_path(cleaned))
+
+    for match in NUMBER_WITH_UNIT_RE.findall(text_no_code):
+        facts.add(match.lower())
+
+    return facts
+
+
+def load_must_contain(fixture_dir: Path) -> list[str]:
+    """Optional explicit must-contain assertions, one per line."""
+    must_contain_file = fixture_dir / "must_contain.txt"
+    if not must_contain_file.exists():
+        return []
+    return [
+        line.strip()
+        for line in must_contain_file.read_text().splitlines()
+        if line.strip() and not line.strip().startswith("#")
+    ]
+
+
+def evaluate_fixture(
+    fixture_dir: Path,
+    concise_budget: float,
+    strict_budget: float,
+) -> dict:
+    default_file = fixture_dir / "default.md"
+    concise_file = fixture_dir / "concise.md"
+    strict_file = fixture_dir / "strict.md"
+
+    for path in (default_file, concise_file, strict_file):
+        if not path.exists():
+            return {
+                "fixture": fixture_dir.name,
+                "ok": False,
+                "error": f"missing file: {path.name}",
+            }
+
+    default_text = default_file.read_text()
+    concise_text = concise_file.read_text()
+    strict_text = strict_file.read_text()
+
+    default_tokens = count_tokens(default_text)
+    concise_tokens = count_tokens(concise_text)
+    strict_tokens = count_tokens(strict_text)
+
+    if default_tokens == 0:
+        return {
+            "fixture": fixture_dir.name,
+            "ok": False,
+            "error": "default.md empty",
+        }
+
+    concise_ratio = concise_tokens / default_tokens
+    strict_ratio = strict_tokens / default_tokens
+
+    default_facts = extract_facts(default_text)
+    concise_facts = extract_facts(concise_text)
+    strict_facts = extract_facts(strict_text)
+
+    concise_missing = sorted(default_facts - concise_facts)
+    strict_missing = sorted(default_facts - strict_facts)
+
+    must_contain = load_must_contain(fixture_dir)
+    concise_required_missing = [
+        item for item in must_contain if item not in concise_text
+    ]
+    strict_required_missing = [
+        item for item in must_contain if item not in strict_text
+    ]
+
+    budget_ok_concise = concise_ratio <= concise_budget
+    budget_ok_strict = strict_ratio <= strict_budget
+    facts_ok_concise = not concise_required_missing
+    facts_ok_strict = not strict_required_missing
+
+    return {
+        "fixture": fixture_dir.name,
+        "ok": budget_ok_concise
+        and budget_ok_strict
+        and facts_ok_concise
+        and facts_ok_strict,
+        "default_tokens": default_tokens,
+        "concise_tokens": concise_tokens,
+        "strict_tokens": strict_tokens,
+        "concise_ratio": round(concise_ratio, 3),
+        "strict_ratio": round(strict_ratio, 3),
+        "concise_budget_ok": budget_ok_concise,
+        "strict_budget_ok": budget_ok_strict,
+        "concise_advisory_missing": concise_missing,
+        "strict_advisory_missing": strict_missing,
+        "concise_required_missing": concise_required_missing,
+        "strict_required_missing": strict_required_missing,
+    }
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument(
+        "--fixtures",
+        type=Path,
+        default=Path("tests/fixtures/output-modes"),
+        help="Path to fixtures directory",
+    )
+    parser.add_argument(
+        "--concise-budget",
+        type=float,
+        default=CONCISE_BUDGET_DEFAULT,
+        help=f"Max concise/default token ratio (default {CONCISE_BUDGET_DEFAULT})",
+    )
+    parser.add_argument(
+        "--strict-budget",
+        type=float,
+        default=STRICT_BUDGET_DEFAULT,
+        help=f"Max strict/default token ratio (default {STRICT_BUDGET_DEFAULT})",
+    )
+    parser.add_argument(
+        "--json",
+        action="store_true",
+        help="Emit JSON report instead of human format",
+    )
+    args = parser.parse_args()
+
+    if not args.fixtures.is_dir():
+        print(f"error: fixtures dir not found: {args.fixtures}", file=sys.stderr)
+        return 2
+
+    fixture_dirs = sorted(
+        d for d in args.fixtures.iterdir() if d.is_dir() and (d / "default.md").exists()
+    )
+
+    if not fixture_dirs:
+        print(f"error: no fixtures found under {args.fixtures}", file=sys.stderr)
+        return 2
+
+    results = [
+        evaluate_fixture(d, args.concise_budget, args.strict_budget)
+        for d in fixture_dirs
+    ]
+
+    total_default = sum(r.get("default_tokens", 0) for r in results)
+    total_concise = sum(r.get("concise_tokens", 0) for r in results)
+    total_strict = sum(r.get("strict_tokens", 0) for r in results)
+    aggregate = {
+        "concise_ratio": round(total_concise / total_default, 3) if total_default else 0,
+        "strict_ratio": round(total_strict / total_default, 3) if total_default else 0,
+        "fixtures": len(results),
+        "passed": sum(1 for r in results if r.get("ok")),
+    }
+
+    if args.json:
+        print(json.dumps({"results": results, "aggregate": aggregate}, indent=2))
+    else:
+        print(f"{'fixture':<28} {'default':>8} {'concise':>8} {'strict':>8} {'c%':>6} {'s%':>6} {'ok':>4}")
+        print("-" * 76)
+        for r in results:
+            if "error" in r:
+                print(f"{r['fixture']:<28} ERROR: {r['error']}")
+                continue
+            mark = "yes" if r["ok"] else "NO"
+            print(
+                f"{r['fixture']:<28} {r['default_tokens']:>8} "
+                f"{r['concise_tokens']:>8} {r['strict_tokens']:>8} "
+                f"{int(r['concise_ratio'] * 100):>5}% "
+                f"{int(r['strict_ratio'] * 100):>5}% {mark:>4}"
+            )
+        print("-" * 76)
+        print(
+            f"aggregate: concise={int(aggregate['concise_ratio'] * 100)}% "
+            f"strict={int(aggregate['strict_ratio'] * 100)}% "
+            f"passed={aggregate['passed']}/{aggregate['fixtures']}"
+        )
+
+    all_ok = all(r.get("ok") for r in results)
+    return 0 if all_ok else 1
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/app/skills/briefing/SKILL.md

@@ -18,6 +18,8 @@ Triggers the Chief of Staff to generate an executive summary.
 /briefing [period]
 # Example: /briefing today
 # Example: /briefing week
+/briefing --tokens [--since 7d|24h|30m]
+# Reports real session token usage from Claude Code JSONL.
 ```
 
 ## Protocol
@@ -58,6 +60,65 @@ Triggers the Chief of Staff to generate an executive summary.
 - "Recent runs" without an explicit time bound defaults to **everything** on some log backends. Always pass `--since` or a date filter, or you will read a week into yesterday's memory.
 - Successful runs outnumber interesting runs by an order of magnitude. Aggressively filter green/noop entries — they are the signal's noise floor.
 
+## Token Receipts
+
+The `--tokens` flag reports real token usage parsed from Claude Code session JSONL — not estimates. Useful for:
+
+- Verifying `output-mode: concise` actually reduces tokens vs default sessions
+- Spotting expensive runs before they show up on the bill
+- Capturing a baseline before changing prompts or skills
+
+Underlying script: `scripts/session_token_stats.py`.
+
+```bash
+# Aggregate current session
+python3 scripts/session_token_stats.py --json
+
+# Statusline-friendly one-line output
+python3 scripts/session_token_stats.py --statusline
+
+# Trend vs baseline
+python3 scripts/session_token_stats.py --statusline --baseline ~/.softspark/ai-toolkit/baseline.json
+```
+
+### Status line (installed by default in v3.2.0+)
+
+`ai-toolkit install` wires `~/.claude/settings.json` to `app/hooks/ai-toolkit-statusline.sh`. The hook reads native Claude Code statusLine stdin (no session JSONL parsing) and renders one line:
+
+```
+➜ <dir> git:(branch) ✗ ████░░░░░░ 43%  ↑6.5k ↓252k effort:xhigh <model>
+```
+
+Segments left to right:
+
+- `➜ <dir>` — current directory basename
+- `git:(branch) ✗` — git branch + dirty marker
+- 10-cell **progress bar** for context-window usage. Color tiers: green `<70%`, orange `70–89%`, red `≥90%`
+- `↑in ↓out` — token arrows. Green up = input (upload), red down = output (download). Both cumulative across the session.
+- `effort:level` — Claude Code effort level (low / medium / high / xhigh)
+- model name
+
+Custom statusLine entries you set yourself (without the `_source: ai-toolkit` tag) are preserved untouched on install.
+
+Opt-outs (no reinstall required):
+
+- `AI_TOOLKIT_STATUSLINE_DISABLE=1` — silence the line entirely
+- `AI_TOOLKIT_STATUSLINE_NO_TOKENS=1` — hide token arrows segment
+- `AI_TOOLKIT_STATUSLINE_NO_GIT=1` — hide git segment
+- `AI_TOOLKIT_STATUSLINE_NO_EFFORT=1` — hide effort level segment
+- `AI_TOOLKIT_STATUSLINE_NO_COLOR=1` — disable ANSI colors
+- `AI_TOOLKIT_STATUSLINE_SHOW_COST=1` — append Claude Code's reported cost (`cost.total_cost_usd`)
+- `AI_TOOLKIT_STATUSLINE_DUMP=1` — write received stdin to `/tmp/cc-statusline-input.json` (debug)
+
+### Save a baseline
+
+```bash
+python3 scripts/session_token_stats.py --json | jq '.totals' > ~/.softspark/ai-toolkit/baseline.json
+export AI_TOOLKIT_STATUSLINE_BASELINE=~/.softspark/ai-toolkit/baseline.json
+```
+
+The statusline then renders trend arrows (↑ / ↓) against that baseline.
+
 ## When NOT to Use
 
 - For a specific production incident — use `/workflow incident-response`

package/app/skills/swarm/SKILL.md

@@ -3,7 +3,7 @@ name: swarm
 description: "Execute tasks via Map-Reduce, Consensus, or Relay swarms"
 user-invocable: true
 effort: max
-argument-hint: "[map-reduce|consensus|relay] [task]"
+argument-hint: "[map-reduce|consensus|relay] [--with-kb] [--worktree] [task]"
 context: fork
 agent: orchestrator
 model: opus
@@ -79,3 +79,85 @@ Agent(
 2. De-duplicate identical findings
 3. Synthesize unique insights
 4. Generate final swarm report
+
+## KB-First Mode (`--with-kb`)
+
+When `$ARGUMENTS` contains `--with-kb`, every spawned agent MUST receive KB context grounded in the project knowledge base.
+
+### Required pre-flight (run BEFORE spawning agents)
+
+1. Call `mcp__rag-mcp__smart_query` with the original task as `query`. Use `use_multi_hop=true` if the task spans 2+ concepts.
+2. Capture `results[*].kb_id`, `title`, `content`, and `source_documents_used`.
+3. Build a `[KB CONTEXT]` block (max 10 entries, pruned to top scores).
+
+### Per-agent prompt template (mandatory under `--with-kb`)
+
+```
+[KB CONTEXT — from rag-mcp smart_query, ground all decisions in these]
+- {kb_id}: {title}
+  {content excerpt, ≤300 chars}
+- ...
+
+[YOUR SUB-TASK]
+{specific sub-task, owned files, success criteria}
+
+[RULES]
+- Cite KB entries as [PATH: kb_id] when you rely on them.
+- If KB is silent on a decision, state that explicitly — do NOT invent.
+- After producing your output, call mcp__rag-mcp__verify_answer with your answer + the cited kb_ids; include the verdict in your final report.
+```
+
+### Aggregation under `--with-kb`
+
+The synthesis step MUST include a `## KB Coverage` section listing which `kb_id`s were actually cited and any agent that returned `verdict: unsupported`.
+
+### When to skip `--with-kb`
+
+- Pure code-mechanical tasks (rename, format, dependency bump) — KB adds noise.
+- Tasks already scoped to one file with no cross-cutting concerns.
+
+## Isolated Worktrees Mode (`--worktree`)
+
+When `$ARGUMENTS` contains `--worktree`, every spawned agent in **Map-Reduce** mode runs in its own git worktree on a throwaway branch. Aggregation merges or copies the changes back into the lead workspace.
+
+### Why
+
+- Agents touching adjacent files (same module, different functions) can race.
+- Writing to disjoint paths is not enough — file-locking, formatter cache, IDE indexers, and `.git/index.lock` all leak.
+- Worktrees give each agent a real filesystem-level boundary plus a named branch for review.
+
+### How (mandatory under `--worktree`)
+
+Pass `isolation: "worktree"` to every `Agent` call:
+
+```
+Agent(
+  subagent_type="...",
+  description="...",
+  prompt="...",
+  isolation="worktree"
+)
+```
+
+The Agent tool returns the worktree path and branch name on completion. **Empty worktrees are auto-cleaned** by the runtime when the agent made no changes — you don't have to.
+
+### Aggregation under `--worktree`
+
+After all agents return:
+
+1. List the returned `(path, branch)` pairs.
+2. For each non-empty result: `cd <main repo> && git merge --no-ff <branch>` (or cherry-pick the commits if the agent didn't commit).
+3. If any merge conflicts → escalate, do NOT auto-resolve. Cite which two agents touched the same hunk.
+4. After successful merge → delete the worktree: `git worktree remove <path>` and the throwaway branch.
+
+### When `--worktree` is mandatory (not optional)
+
+- Map-Reduce with N≥3 agents touching the same module tree
+- Any task that runs the project formatter or codegen
+- Any task that mutates lockfiles, migrations, or generated artifacts
+
+### When to skip `--worktree`
+
+- Consensus mode — agents return analysis text, not file changes.
+- Relay mode — sequential by design, next agent reads prior agent's commit.
+- Single-agent fallback or KB-only research swarms.