@softspark/ai-toolkit 2.2.0 → 2.3.1

package/AGENTS.md

@@ -602,7 +602,7 @@ Tools: `sync_tasks`, `read_cached_tasks`, `update_task_status`, `update_task`, `
 3. `get_task_details(task_key="PROJ-123")` -- deep dive (description + comments as markdown)
 4. `update_task_status(...)` / `add_task_comment(...)` / `log_task_time(...)` -- mutate
 
-## Comment Templates (8 built-in)
+## Comment Templates (built-in)
 
 | ID | Use for |
 |----|---------|

package/CHANGELOG.md

@@ -7,6 +7,26 @@ Versioning follows [Semantic Versioning](https://semver.org/).
 
 ---
 
+## v2.3.1 — Release Quality Gate (2026-04-14)
+
+### Fixed
+- **README "What's New" section** — was stuck at v2.1.3, now auto-validated by `validate.py --strict`
+- **Release SOP** — added mandatory "Update README What's New" step to Phase 3 checklist
+
+---
+
+## v2.3.0 — Jira MCP Template & Cross-Editor Sync (2026-04-14)
+
+### Added
+- **Jira MCP template** — `ai-toolkit mcp add jira` installs `@softspark/jira-mcp` via global binary. Templates now support `postInstall` field for first-time setup hints shown after `mcp add`, `mcp install`, and `mcp show`. MCP template count: 25 → 26.
+- **MCP template tracking** — globally installed templates are recorded in `state.json`. `ai-toolkit update` automatically syncs tracked templates to Claude global config. `ai-toolkit status` shows tracked MCP templates. "Install once, sync everywhere."
+
+### Fixed
+- **Claude MCP config paths** — corrected to `~/.claude.json` (global) and `.mcp.json` (project) per official Claude Code docs. Previously wrote to `~/.claude/settings.json` and `.claude/settings.local.json`.
+- **Jira MCP template uses global binary** — `jira-mcp` instead of `npx -y` for faster startup and offline support
+
+---
+
 ## v2.2.0 — URL Rules & Registry Safety (2026-04-14)
 
 ### Added

package/README.md

@@ -6,16 +6,17 @@
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
 [![Skills](https://img.shields.io/badge/skills-92-brightgreen)](app/skills/)
 [![Agents](https://img.shields.io/badge/agents-44-blue)](app/agents/)
-[![Tests](https://img.shields.io/badge/tests-604%20passing-success)](tests/)
+[![Tests](https://img.shields.io/badge/tests-606%20passing-success)](tests/)
 
 ---
 
-## What's New in v2.1.3
+## What's New in v2.3.1
 
-- **Idempotent update** — `ai-toolkit update` no longer dirties git with extra blank lines in generated files
-- **Custom rules in generators** — `generate:all` preserves registered rules from other repos across all platforms
-- **README restructured** — 951 → 292 lines with TOC, links to KB docs
-- **3 new KB docs** — CLI Reference, Unique Features, Ecosystem Comparison
+- **URL rule registration** — `ai-toolkit add-rule https://...` with auto-refresh on every update
+- **Jira MCP template** — `ai-toolkit mcp add jira` with `postInstall` setup hints
+- **MCP template tracking** — globally installed templates saved in `state.json`, auto-synced on `update`
+- **Race condition fix** — parallel project updates no longer drop registry entries (fcntl.flock + atomic writes)
+- **Claude MCP paths fixed** — now uses `~/.claude.json` (global) and `.mcp.json` (project) per official docs
 
 See [CHANGELOG.md](CHANGELOG.md) for full history.
 
@@ -142,7 +143,7 @@ ai-toolkit/
 │   └── ARCHITECTURE.md  # Full system design
 ├── kb/                  # Reference docs, procedures, plans
 ├── scripts/             # Validation, install, evaluation scripts
-├── tests/               # Bats test suite (604 tests)
+├── tests/               # Bats test suite (606 tests)
 └── CHANGELOG.md
 ```
 
@@ -174,7 +175,7 @@ ai-toolkit/
 
 **68 language rules** — 13 languages, 5 categories each. Auto-detected or explicit `--lang`. See [Language Rules](kb/reference/language-rules.md).
 
-**25 MCP templates** — Ready-to-use configs for GitHub, PostgreSQL, Slack, Sentry, and more. See [MCP Templates](kb/reference/mcp-templates.md).
+**26 MCP templates** — Ready-to-use configs for GitHub, PostgreSQL, Slack, Jira, Sentry, and more. See [MCP Templates](kb/reference/mcp-templates.md).
 
 See [Unique Features](kb/reference/unique-features.md) for detailed descriptions of all differentiators.
 

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

package/app/ARCHITECTURE.md

@@ -302,7 +302,7 @@ Lead Session (You)
 ## Extension Points
 
 ### MCP Templates (25)
-`app/plugins/mcp-templates/` ships 25 ready-to-use MCP server config templates (filesystems, databases, GitHub, Slack, etc.). Opt-in via `ai-toolkit install --modules mcp-templates` or activated automatically with `--profile strict|full`.
+`app/plugins/mcp-templates/` ships 26 ready-to-use MCP server config templates (filesystems, databases, GitHub, Slack, etc.). Opt-in via `ai-toolkit install --modules mcp-templates` or activated automatically with `--profile strict|full`.
 
 ### Language Rules (68 files, 13 languages)
 `app/rules/` contains per-language coding rules. Supported languages: TypeScript, Python, Go, Rust, Java, Kotlin, Swift, Dart, C#, PHP, C++, Ruby, and common (shared). Auto-detected from project files via `--auto-detect` or selected with `--modules rules-<lang>`.

package/app/mcp-templates/README.md

@@ -77,6 +77,7 @@ Example -- adding GitHub to `.mcp.json`:
 | `vercel` | Vercel deployments and settings |
 | `datadog` | Datadog monitoring and metrics |
 | `grafana` | Grafana dashboards and alerting |
+| `jira` | Jira multi-instance routing, ADF, caching, comment templates |
 | `custom-template` | Empty template for custom servers |
 
 ## Contributing a new template
@@ -100,6 +101,7 @@ Example -- adding GitHub to `.mcp.json`:
 ```
 
 2. Use `${ENV_VAR}` syntax for any secrets or tokens
-3. Keep the `name` field matching the filename (without `.json`)
-4. Update this README table
-5. Run `python3 scripts/validate.py` to verify
+3. Optional: add `"postInstall": "setup instructions"` for first-time config hints
+4. Keep the `name` field matching the filename (without `.json`)
+5. Update this README table
+6. Run `python3 scripts/validate.py` to verify

package/app/mcp-templates/jira.json

@@ -0,0 +1,11 @@
+{
+  "name": "jira",
+  "description": "Jira integration — multi-instance routing, ADF formatting, task caching, and comment templates",
+  "mcpServers": {
+    "jira": {
+      "command": "jira-mcp",
+      "args": []
+    }
+  },
+  "postInstall": "Run 'npm install -g @softspark/jira-mcp && jira-mcp config init' to install and set up credentials."
+}

package/kb/procedures/release-preparation-sop.md

@@ -157,6 +157,18 @@ Add entry at the top of `CHANGELOG.md` (after the header, before previous releas
 - Date format: `YYYY-MM-DD`
 - Title: short, descriptive, no version number repetition
 
+### Update README "What's New" section
+
+**MANDATORY on every release.** Update the `## What's New in vX.Y.Z` section in `README.md`:
+
+1. Change the heading version: `## What's New in vX.Y.Z`
+2. Replace bullet points with 3-5 highlights from this release
+3. Keep the `See [CHANGELOG.md](CHANGELOG.md) for full history.` link
+
+> **Warning:** This section is the first thing users see after the badges.
+> A stale version here (e.g., "What's New in v2.1.3" when shipping v2.3.0)
+> signals an unmaintained project. Do NOT skip this step.
+
 ---
 
 ## Phase 4: Regenerate Artifacts

package/kb/reference/architecture-overview.md

@@ -335,7 +335,7 @@ Severity levels: HIGH (blocks deployment), WARN (should fix), INFO (best practic
 ## Extension Points
 
 ### MCP Templates
-`app/plugins/mcp-templates/` contains 25 ready-to-use MCP server config templates. Opt-in via `ai-toolkit install --modules mcp-templates` or activated automatically with `--profile strict|full`.
+`app/plugins/mcp-templates/` contains 26 ready-to-use MCP server config templates. Opt-in via `ai-toolkit install --modules mcp-templates` or activated automatically with `--profile strict|full`.
 
 ### Language Rules
 `app/rules/` provides language-specific rule files covering 13 languages (TypeScript, Python, Go, Rust, Java, Kotlin, Swift, Dart, C#, PHP, C++, Ruby, common). Auto-detected from project files via `--auto-detect` or selectable with `--modules rules-<lang>`. See README.md for current count.

package/kb/reference/cli-reference.md

@@ -43,7 +43,7 @@ Usage: ai-toolkit <command> [options]
 
 | Command | Description |
 |---------|-------------|
-| `mcp list` | List available MCP server templates (25 templates) |
+| `mcp list` | List available MCP server templates (26 templates) |
 | `mcp editors` | List editors with native MCP config adapters and scopes |
 | `mcp add <name> [names...]` | Add MCP server template(s) to `.mcp.json` |
 | `mcp install --editor <name[,..]> [names...]` | Install templates into native editor MCP config |

package/kb/reference/manifest-install.md

@@ -39,7 +39,7 @@ Modules are defined in `manifest.json` at the repository root. There are 17 modu
 | `rules-php` | PHP-specific rules (5 files) | auto-detect |
 | `rules-cpp` | C++-specific rules (5 files) | auto-detect |
 | `rules-ruby` | Ruby-specific rules (5 files) | auto-detect |
-| `mcp-templates` | 25 MCP server config templates | strict, full |
+| `mcp-templates` | 26 MCP server config templates | strict, full |
 
 ## Profiles
 

package/kb/reference/mcp-templates.md

@@ -6,14 +6,14 @@ tags: [mcp, templates, servers, configuration, editors]
 version: "1.1.0"
 created: "2026-04-07"
 last_updated: "2026-04-12"
-description: "Reference for 25 MCP server templates plus native editor MCP installation support."
+description: "Reference for 26 MCP server templates plus native editor MCP installation support."
 ---
 
 # MCP Server Templates
 
 ## Overview
 
-ai-toolkit ships 25 ready-to-use MCP server configuration templates in `app/mcp-templates/`. Each template is a JSON file that defines the canonical `mcpServers` block for a specific service. Templates can be merged into the project's `.mcp.json` and rendered into editor-native MCP config files via the `ai-toolkit mcp` CLI subcommand.
+ai-toolkit ships 26 ready-to-use MCP server configuration templates in `app/mcp-templates/`. Each template is a JSON file that defines the canonical `mcpServers` block for a specific service. Templates can be merged into the project's `.mcp.json` and rendered into editor-native MCP config files via the `ai-toolkit mcp` CLI subcommand.
 
 ## CLI
 

package/llms-full.txt

@@ -3669,6 +3669,18 @@ Add entry at the top of `CHANGELOG.md` (after the header, before previous releas
 - Date format: `YYYY-MM-DD`
 - Title: short, descriptive, no version number repetition
 
+### Update README "What's New" section
+
+**MANDATORY on every release.** Update the `## What's New in vX.Y.Z` section in `README.md`:
+
+1. Change the heading version: `## What's New in vX.Y.Z`
+2. Replace bullet points with 3-5 highlights from this release
+3. Keep the `See [CHANGELOG.md](CHANGELOG.md) for full history.` link
+
+> **Warning:** This section is the first thing users see after the badges.
+> A stale version here (e.g., "What's New in v2.1.3" when shipping v2.3.0)
+> signals an unmaintained project. Do NOT skip this step.
+
 ---
 
 ## Phase 4: Regenerate Artifacts
@@ -4774,7 +4786,7 @@ Severity levels: HIGH (blocks deployment), WARN (should fix), INFO (best practic
 ## Extension Points
 
 ### MCP Templates
-`app/plugins/mcp-templates/` contains 25 ready-to-use MCP server config templates. Opt-in via `ai-toolkit install --modules mcp-templates` or activated automatically with `--profile strict|full`.
+`app/plugins/mcp-templates/` contains 26 ready-to-use MCP server config templates. Opt-in via `ai-toolkit install --modules mcp-templates` or activated automatically with `--profile strict|full`.
 
 ### Language Rules
 `app/rules/` provides language-specific rule files covering 13 languages (TypeScript, Python, Go, Rust, Java, Kotlin, Swift, Dart, C#, PHP, C++, Ruby, common). Auto-detected from project files via `--auto-detect` or selectable with `--modules rules-<lang>`. See README.md for current count.
@@ -5164,7 +5176,7 @@ Usage: ai-toolkit <command> [options]
 
 | Command | Description |
 |---------|-------------|
-| `mcp list` | List available MCP server templates (25 templates) |
+| `mcp list` | List available MCP server templates (26 templates) |
 | `mcp editors` | List editors with native MCP config adapters and scopes |
 | `mcp add <name> [names...]` | Add MCP server template(s) to `.mcp.json` |
 | `mcp install --editor <name[,..]> [names...]` | Install templates into native editor MCP config |
@@ -7814,7 +7826,7 @@ Modules are defined in `manifest.json` at the repository root. There are 17 modu
 | `rules-php` | PHP-specific rules (5 files) | auto-detect |
 | `rules-cpp` | C++-specific rules (5 files) | auto-detect |
 | `rules-ruby` | Ruby-specific rules (5 files) | auto-detect |
-| `mcp-templates` | 25 MCP server config templates | strict, full |
+| `mcp-templates` | 26 MCP server config templates | strict, full |
 
 ## Profiles
 
@@ -8018,14 +8030,14 @@ tags: [mcp, templates, servers, configuration, editors]
 version: "1.1.0"
 created: "2026-04-07"
 last_updated: "2026-04-12"
-description: "Reference for 25 MCP server templates plus native editor MCP installation support."
+description: "Reference for 26 MCP server templates plus native editor MCP installation support."
 ---
 
 # MCP Server Templates
 
 ## Overview
 
-ai-toolkit ships 25 ready-to-use MCP server configuration templates in `app/mcp-templates/`. Each template is a JSON file that defines the canonical `mcpServers` block for a specific service. Templates can be merged into the project's `.mcp.json` and rendered into editor-native MCP config files via the `ai-toolkit mcp` CLI subcommand.
+ai-toolkit ships 26 ready-to-use MCP server configuration templates in `app/mcp-templates/`. Each template is a JSON file that defines the canonical `mcpServers` block for a specific service. Templates can be merged into the project's `.mcp.json` and rendered into editor-native MCP config files via the `ai-toolkit mcp` CLI subcommand.
 
 ## CLI
 

package/manifest.json

@@ -1,5 +1,5 @@
 {
-  "version": "2.2.0",
+  "version": "2.3.1",
   "components": {
     "agents": {
       "description": "44 specialized agents (orchestrator, backend, frontend, security, devops, etc.)",
@@ -146,7 +146,7 @@
       "auto_detect": ["Gemfile", "*.gemspec"]
     },
     "mcp-templates": {
-      "description": "25 MCP server config templates",
+      "description": "26 MCP server config templates",
       "default": false
     }
   },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@softspark/ai-toolkit",
-  "version": "2.2.0",
+  "version": "2.3.1",
   "description": "Professional-grade AI coding toolkit: 92 skills, 44 agents, multi-platform support (Claude, Cursor, Windsurf, Copilot, Gemini, Cline, Roo Code, Aider, Augment, Google Antigravity, Codex CLI), machine-enforced safety constitution, persona presets, skill security auditor, expanded lifecycle hooks, 11 plugin packs, and benchmark tooling.",
   "keywords": [
     "claude",

package/scripts/install.py

@@ -432,6 +432,38 @@ def install_claude_code(target_dir: Path, hooks_scripts_dir: Path,
     inject_rules(claude_dir, target_dir, rules_dir, only, skip, dry_run,
                  refresh_urls=True)
 
+    _sync_mcp_templates(dry_run)
+
+
+def _sync_mcp_templates(dry_run: bool) -> None:
+    """Re-install tracked MCP templates into Claude global config."""
+    from install_steps.install_state import get_mcp_templates
+
+    templates = get_mcp_templates()
+    if not templates:
+        return
+
+    if dry_run:
+        print(f"  Would sync MCP templates: {', '.join(templates)}")
+        return
+
+    from mcp_editors import install_servers
+
+    servers: dict = {}
+    for name in templates:
+        try:
+            tpl_path = app_dir / "mcp-templates" / f"{name}.json"
+            if tpl_path.is_file():
+                import json as _json
+                data = _json.loads(tpl_path.read_text(encoding="utf-8"))
+                servers.update(data.get("mcpServers", {}))
+        except Exception:
+            pass  # Skip broken templates silently
+
+    if servers:
+        install_servers(["claude"], servers, scope="global")
+        print(f"  MCP synced: {', '.join(templates)}")
+
 
 VALID_PERSONAS = ("backend-lead", "frontend-lead", "devops-eng", "junior-dev")
 

package/scripts/install_steps/install_state.py

@@ -60,6 +60,31 @@ def get_installed_profile() -> str:
     return state.get("profile", "")
 
 
+def get_mcp_templates() -> list[str]:
+    """Return list of globally tracked MCP template names."""
+    state = load_state()
+    templates = state.get("mcp_templates", [])
+    return templates if isinstance(templates, list) else []
+
+
+def record_mcp_template(name: str) -> None:
+    """Add a template name to the tracked set in state.json."""
+    state = load_state()
+    templates = set(state.get("mcp_templates", []))
+    templates.add(name)
+    state["mcp_templates"] = sorted(templates)
+    save_state(state)
+
+
+def remove_mcp_template(name: str) -> None:
+    """Remove a template name from the tracked set in state.json."""
+    state = load_state()
+    templates = set(state.get("mcp_templates", []))
+    templates.discard(name)
+    state["mcp_templates"] = sorted(templates)
+    save_state(state)
+
+
 def _now_iso() -> str:
     """Return current UTC time in ISO 8601 format."""
     return datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")
@@ -138,6 +163,10 @@ def print_status() -> None:
         langs = [m.replace("rules-", "") for m in detected]
         print(f"  Detected:   {', '.join(langs)}")
 
+    mcp = state.get("mcp_templates", [])
+    if mcp:
+        print(f"  MCP:        {', '.join(mcp)}")
+
     extends = state.get("extends")
     if extends:
         print(f"  Extends:    {extends.get('source', 'unknown')}")

package/scripts/mcp_editors.py

@@ -15,8 +15,8 @@ except ModuleNotFoundError:  # pragma: no cover - Python 3.11+ should have tomll
 EDITOR_SPECS: dict[str, dict[str, str | None]] = {
     "claude": {
         "label": "Claude Code",
-        "project_path": ".claude/settings.local.json",
-        "global_path": ".claude/settings.json",
+        "project_path": ".mcp.json",
+        "global_path": ".claude.json",
         "format": "json",
         "doc_scope": "project + global",
     },

package/scripts/mcp_manager.py

@@ -130,6 +130,11 @@ def cmd_show(name: str) -> None:
         for key, val in env_vars:
             print(f"  {key} = {val}")
 
+    post_install = data.get("postInstall")
+    if post_install:
+        print()
+        print(f"Setup: {post_install}")
+
 
 def cmd_add(names: list[str], target_dir: Path) -> None:
     """Add one or more MCP templates to .mcp.json."""
@@ -155,6 +160,13 @@ def cmd_add(names: list[str], target_dir: Path) -> None:
     write_mcp_config(target_dir, config)
     print(f"Added: {', '.join(added)}")
 
+    # Show postInstall hints from added templates
+    for name in names:
+        data = load_template(name)
+        post_install = data.get("postInstall")
+        if post_install:
+            print(f"\n  Note ({name}): {post_install}")
+
 
 def cmd_install(
     names: list[str],
@@ -203,6 +215,20 @@ def cmd_install(
     for path in updated:
         print(f"Updated: {path}")
 
+    # Track globally installed templates in state.json
+    if eff_scope == "global" and names:
+        from install_steps.install_state import record_mcp_template
+        for name in names:
+            record_mcp_template(name)
+
+    # Show postInstall hints from installed templates
+    if names:
+        for name in names:
+            data = load_template(name)
+            post_install = data.get("postInstall")
+            if post_install:
+                print(f"\n  Note ({name}): {post_install}")
+
 
 def cmd_remove(name: str, target_dir: Path | None, *, editors: list[str], scope: str | None) -> None:
     """Remove an MCP server from .mcp.json."""
@@ -223,6 +249,9 @@ def cmd_remove(name: str, target_dir: Path | None, *, editors: list[str], scope:
             )
         else:
             updated = remove_servers(editors, [name], scope="global")
+            # Untrack globally removed template from state.json
+            from install_steps.install_state import remove_mcp_template
+            remove_mcp_template(name)
         for path in updated:
             print(f"Updated: {path}")
         print(f"Removed: {name}")

package/scripts/validate.py

@@ -646,6 +646,23 @@ def _validate_version_sync(tk_dir: Path, vr: ValidationResult) -> None:
         detail = ", ".join(f"{k}={v}" for k, v in versions.items())
         vr.error(f"Version mismatch across files: {detail}")
 
+    # Check README "What's New" section matches current version
+    pkg_version = versions.get("package.json", "")
+    if pkg_version:
+        readme = tk_dir / "README.md"
+        if readme.is_file():
+            content = readme.read_text(encoding="utf-8")
+            m = re.search(r"## What's New in v([\d.]+)", content)
+            if m:
+                whats_new_ver = m.group(1)
+                if whats_new_ver == pkg_version:
+                    print(f"  OK: README \"What's New\" (v{whats_new_ver})")
+                else:
+                    vr.error(
+                        f"README \"What's New in v{whats_new_ver}\" "
+                        f"is stale (package.json is v{pkg_version})"
+                    )
+
 
 def validate_content_quality(tk_dir: Path, vr: ValidationResult) -> None:
     """Check content quality: name matches directory, non-empty body."""