@softspark/ai-toolkit 4.0.0 → 4.1.0

package/CHANGELOG.md

@@ -7,6 +7,65 @@ Versioning follows [Semantic Versioning](https://semver.org/).
 
 ---
 
+## v4.1.0 — Default `output-mode: concise` propagated to all editors (2026-05-06)
+
+Minor release. Adds a global `output-mode: concise` directive that propagates to every editor config produced by ai-toolkit. Reduces token usage and removes preamble/filler from assistant responses across Claude Code, Cursor, Windsurf, Cline, Roo Code, Augment, Codex, Antigravity, GitHub Copilot, Gemini CLI, and Aider.
+
+### Added
+
+- **`app/rules/output-mode.md`** — auto-injected into `~/.claude/CLAUDE.md` (global) and project-local `CLAUDE.md` via the existing `inject_rules()` mechanism on every `ai-toolkit install` / `ai-toolkit update`.
+- **`rule_output_mode()` in `scripts/dir_rules_shared.py`** — registered in `STANDARD_RULES`, so directory-based generators (Cursor `.mdc`, Windsurf, Cline, Roo, Augment, Codex, Antigravity) emit a dedicated `ai-toolkit-output-mode.md` file alongside the other six standard rules.
+- **Output Mode block in `scripts/generator_base.render_generator()`** — single-file editor outputs (`GEMINI.md`, `.github/copilot-instructions.md`, `.cursorrules`, Aider `CONVENTIONS.md`) now include the directive between TOOLKIT markers.
+
+### Directives
+
+The `concise` mode applies these rules to assistant responses:
+
+- No preamble — skip "I'll now…", "Sure, let me…", "Great question!"
+- Lead with the result; explanation only if asked or non-obvious.
+- Max 3 sentences per closed question.
+- Tables and lists over prose for comparisons, steps, values.
+- No trailing summaries when the diff or output already shows what changed.
+- Drop filler adjectives ("nice", "great", "powerful", "robust").
+- Cite as `path:line`, not paragraphs of location prose.
+- Escalate to verbose only for architecture / RFC / ADR / trade-off documents or explicit user request.
+
+### Changed
+
+- **Standard rule count for directory-based generators: 6 → 7**. Tests updated: `tests/test_generators.bats` (count assertions in two cases bumped from 6/8 to 7/9).
+
+### How to opt out
+
+- Per-session: `/brand-voice default` (or `/brand-voice strict` for tighter)
+- Per-project: edit `output-mode:` value in project's `CLAUDE.md` or strip the `<!-- TOOLKIT:output-mode -->` block manually
+- Re-install without rules: `ai-toolkit install --skip rules`
+
+### Why
+
+User feedback after v4.0.x consolidation: asked for a hook-like mechanism to enforce concise responses. The `brand-voice` skill already had `concise`/`strict` modes (shipped v3.2.0) but activation required per-project opt-in. This release flips the default to opt-out — every editor that consumes ai-toolkit configs now sees the directive immediately after install/update.
+
+---
+
+## v4.0.1 — CI hotfix: README "What You Get" table counts (2026-05-06)
+
+Patch release. Fixes CI failure on v4.0.0 main branch — three `tests/test_metadata_contracts.bats` cases failed because the `What You Get` table in `README.md` and the skill type table in `kb/reference/architecture-overview.md` still referenced pre-consolidation counts (32 task / 32 hybrid / 48 knowledge).
+
+### Fixed
+
+- **README.md `What You Get` table**: hybrid 32 → 30, knowledge 48 → 45 (task unchanged at 32; total 107).
+- **`kb/reference/architecture-overview.md`**: same correction in the skill type table.
+- **`manifest.json`**: skill subtype description updated from `(30 task + 31 hybrid + 46 knowledge)` to the correct `(32 task + 30 hybrid + 45 knowledge)`.
+
+### Why
+
+v4.0.0 release path missed these three count locations. They are gated by the metadata contract test suite, which I misread locally (the trailing `ok 1047` line is the *last test number*, not a pass count). Confirmed by re-running `bats tests/test_metadata_contracts.bats` directly, which shows three `not ok` failures.
+
+### Process note
+
+Lesson for future releases: always inspect `bats … 2>&1 | grep "^not ok"` rather than trusting tail of npm test. Updating the release-verification SOP separately.
+
+---
+
 ## v4.0.0 — Skill consolidation: 112 → 107, removes 5 overlapping skills (2026-05-06)
 
 **Breaking release.** Five redundant skills removed; their substantive knowledge migrated into the surviving targets. Resolves the `/skills` listing truncation that v3.5.x partially addressed and removes user-facing overlap that made dispatch ambiguous.

package/README.md

@@ -14,6 +14,17 @@
 
 ---
 
+## What's New in v4.1.0
+
+Default `output-mode: concise` directive now propagates to every editor config (Claude Code global + project-local CLAUDE.md, Cursor `.mdc` rules, Windsurf, Cline, Roo, Augment, Codex `.agents/rules`, Antigravity, GitHub Copilot, Gemini CLI, Aider). Auto-installed on every `ai-toolkit install` / `ai-toolkit update`. The `brand-voice` skill (shipped v3.2.0) auto-loads concise rules; assistants without that skill still see the directive in their config.
+
+- **No preamble**, lead with the result, max 3 sentences per closed question, tables over prose, no trailing summaries.
+- **Opt out**: `/brand-voice default` (session) or strip `<!-- TOOLKIT:output-mode -->` block from CLAUDE.md (permanent).
+
+## What's New in v4.0.1
+
+CI hotfix for v4.0.0. Corrects skill subtype counts in `README.md` "What You Get" table and `kb/reference/architecture-overview.md` (hybrid 32 → 30, knowledge 48 → 45). The metadata contract tests caught the drift on CI; v4.0.0 release path missed three count locations. No skill catalog changes — see v4.0.0 below for the actual consolidation.
+
 ## What's New in v4.0.0
 
 **Breaking release.** Skill catalog consolidated from 112 → 107: removes 5 redundant skills, merges their substantive knowledge into the surviving targets. Eliminates `/skills` truncation and removes overlap that confused agent dispatch.
@@ -138,8 +149,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) | 32 | Slash commands with agent knowledge base |
-| `skills/` (knowledge) | 48 | Domain knowledge auto-loaded by agents (includes 13 `<lang>-rules` skills) |
+| `skills/` (hybrid) | 30 | Slash commands with agent knowledge base |
+| `skills/` (knowledge) | 45 | 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) |

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": "4.0.0",
+  "version": "4.1.0",
   "author": {
     "name": "SoftSpark",
     "url": "https://github.com/softspark"

package/app/rules/output-mode.md

@@ -0,0 +1,28 @@
+# Output Mode
+
+`output-mode: concise`
+
+Default response mode for this project is **concise**. The `brand-voice` skill (when present in ai-toolkit) auto-loads its `concise` rules; assistants without that skill should still apply the directives below.
+
+## Concise Mode Directives
+
+- **No preamble.** Skip "I'll now...", "Sure, let me...", "Great question!" and similar warm-ups. Start with the answer.
+- **Lead with the result.** Conclusion or output first; explanation only if asked or non-obvious.
+- **Max 3 sentences per closed question.** Yes/no, single-fact, or "where is X" answers stay under three sentences.
+- **Tables and lists over prose** when comparing options, listing steps, or showing values.
+- **No trailing summaries.** If the diff or output already shows what changed, do not restate it.
+- **Drop filler adjectives.** No "nice", "great", "powerful", "robust" unless the user asked for evaluation.
+- **Cite file paths as `path:line`** instead of paragraphs describing where things live.
+- **Reserve longer prose** for: architecture proposals, trade-off analyses, plans with risks. Everything else: terse.
+
+## When to escalate to verbose
+
+- User explicitly asks: "explain in detail", "walk me through", "give me the full picture".
+- Reporting a non-obvious failure mode where missing context would mislead.
+- Architecture / RFC / ADR / trade-off documents — those have their own structure.
+
+## How to override
+
+- Per-session: `/brand-voice default` (or `/brand-voice strict` for even tighter)
+- Per-project: change this rule's `output-mode:` value in the project's `CLAUDE.md`
+- Permanent removal: re-run `ai-toolkit install --skip rules` or strip the `<!-- TOOLKIT:output-mode -->` block manually

package/kb/reference/architecture-overview.md

@@ -186,8 +186,8 @@ Three tiers determine how to approach a task:
 | Type | Field | Invocation | Count |
 |------|-------|-----------|-------|
 | Task | `disable-model-invocation: true` | User via `/skill` only | 32 |
-| Hybrid | (neither) | User via `/skill` + agent knowledge | 32 |
-| Knowledge | `user-invocable: false` | Claude auto-loads | 48 |
+| Hybrid | (neither) | User via `/skill` + agent knowledge | 30 |
+| Knowledge | `user-invocable: false` | Claude auto-loads | 45 |
 
 ## Multi-Agent Execution
 

package/llms-full.txt

@@ -6274,8 +6274,8 @@ Three tiers determine how to approach a task:
 | Type | Field | Invocation | Count |
 |------|-------|-----------|-------|
 | Task | `disable-model-invocation: true` | User via `/skill` only | 32 |
-| Hybrid | (neither) | User via `/skill` + agent knowledge | 32 |
-| Knowledge | `user-invocable: false` | Claude auto-loads | 48 |
+| Hybrid | (neither) | User via `/skill` + agent knowledge | 30 |
+| Knowledge | `user-invocable: false` | Claude auto-loads | 45 |
 
 ## Multi-Agent Execution
 

package/manifest.json

@@ -1,5 +1,5 @@
 {
-  "version": "4.0.0",
+  "version": "4.1.0",
   "components": {
     "agents": {
       "description": "44 specialized agents (orchestrator, backend, frontend, security, devops, etc.)",
@@ -9,7 +9,7 @@
       "tags": ["core", "agents"]
     },
     "skills": {
-      "description": "107 skills (30 task + 31 hybrid + 46 knowledge)",
+      "description": "107 skills (32 task + 30 hybrid + 45 knowledge)",
       "path": "app/skills",
       "target": ".claude/skills",
       "type": "symlink",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@softspark/ai-toolkit",
-  "version": "4.0.0",
+  "version": "4.1.0",
   "description": "AI coding toolkit: 107 skills, 44 agents, 12-editor write-through (Claude, Cursor, Windsurf, Copilot, Gemini, Cline, Roo, Aider, Augment, Antigravity, Codex, opencode), machine-enforced safety constitution, SARIF audit, signed npm provenance.",
   "keywords": [
     "claude",

package/scripts/dir_rules_shared.py

@@ -105,6 +105,25 @@ def rule_quality_standards() -> str:
 """
 
 
+def rule_output_mode() -> str:
+    return """\
+# Output Mode
+
+`output-mode: concise`
+
+Default response mode is **concise**. The `brand-voice` skill (when present) auto-loads concise rules; assistants without that skill should still apply the directives below.
+
+* No preamble — skip "I'll now...", "Sure, let me...", "Great question!" Start with the answer.
+* Lead with the result — conclusion or output first; explanation only if asked or non-obvious.
+* Max 3 sentences per closed question — yes/no, single-fact, or "where is X" answers stay under three sentences.
+* Tables and lists over prose — when comparing options, listing steps, or showing values.
+* No trailing summaries — if the diff or output already shows what changed, do not restate it.
+* Drop filler adjectives — no "nice", "great", "powerful", "robust" unless the user asked for evaluation.
+* Cite as `path:line` — instead of paragraphs describing where things live.
+* Escalate to verbose only for: architecture / RFC / ADR / trade-off documents, or when the user asks for detail.
+"""
+
+
 def rule_agents_and_skills() -> str:
     """Full listing of agents and skills — same content all platforms get."""
     agents_count, skills_count = count_agents_and_skills()
@@ -142,6 +161,7 @@ STANDARD_RULES: dict[str, callable] = {
     f"{PREFIX}security.md": rule_security,
     f"{PREFIX}workflow.md": rule_workflow,
     f"{PREFIX}quality-standards.md": rule_quality_standards,
+    f"{PREFIX}output-mode.md": rule_output_mode,
 }
 
 

package/scripts/generator_base.py

@@ -142,6 +142,23 @@ def render_generator(config: dict) -> None:
         print()
         print_toolkit_end()
 
+    # Default output mode directive — applies to every editor that loads this file
+    print()
+    print("<!-- TOOLKIT:output-mode START -->")
+    print("<!-- Auto-injected by ai-toolkit. Re-run to update. -->")
+    print()
+    print("# Output Mode")
+    print()
+    print("`output-mode: concise`")
+    print()
+    print("Default response mode is **concise**. Skip preamble, lead with the result, "
+          "max 3 sentences per closed question, prefer tables/lists over prose, no "
+          "trailing summaries, drop filler adjectives, cite as `path:line`. Escalate "
+          "to verbose only for architecture / RFC / ADR / trade-off documents or when "
+          "the user asks for detail.")
+    print()
+    print("<!-- TOOLKIT:output-mode END -->")
+
     # Registered custom rules from ~/.softspark/ai-toolkit/rules/
     if RULES_DIR.is_dir():
         for rule_file in sorted(RULES_DIR.glob("*.md")):