@softspark/ai-toolkit 2.1.3 → 2.3.0

package/AGENTS.md

@@ -578,28 +578,98 @@ Derived from the immutable safety constitution (5 articles):
 - **No Secrets in Code**: Never commit credentials, API keys, or sensitive configuration values
 <!-- TOOLKIT:ai-toolkit END -->
 
-<!-- TOOLKIT:jira-rules START -->
+<!-- TOOLKIT:jira-mcp START -->
 <!-- Auto-injected by ai-toolkit. Re-run to update. -->
 
 # Jira MCP Server
 
-Tools: `sync_tasks`, `read_cached_tasks`, `update_task_status`, `add_task_comment`, `reassign_task`, `get_task_statuses`, `get_task_details`, `log_task_time`, `get_task_time_tracking`
+Tools: `sync_tasks`, `read_cached_tasks`, `update_task_status`, `update_task`, `add_task_comment`, `reassign_task`, `get_task_statuses`, `get_task_details`, `get_project_language`, `log_task_time`, `get_task_time_tracking`, `list_comment_templates`, `add_templated_comment`, `create_task`, `search_tasks`
 
 ## Key Rules
 
-- **Always `sync_tasks` first** before reading — cache may be stale.
-- **Time format:** `"2h 30m"` — hours and minutes only, never days.
+- **Always `sync_tasks` first** before reading -- cache may be stale.
+- **Language first:** before writing ANY comment, description, or task content, call `get_project_language(project_key)` or check the `language` field in `get_task_details` response. Write ALL content in the project's configured language. Never assume Polish or English — always check first.
+- **Time format:** `"2h 30m"` -- hours and minutes only, never days.
 - **Status changes:** call `get_task_statuses` first to check valid transitions.
 - **Multi-instance:** project key determines which Jira instance is used (mapped in config.json).
+- **Comments are ADF:** `add_task_comment` converts markdown to ADF (Atlassian Document Format) automatically.
+- **Templates:** use `list_comment_templates` to discover available templates, then `add_templated_comment` with `template_id` + `variables`.
 
 ## Workflow
 
-1. `sync_tasks(jql="assignee=currentUser() AND status!=Done")` — fetch fresh
-2. `read_cached_tasks()` — work offline
-3. `get_task_details(task_key="PROJ-123")` — deep dive
-4. `update_task_status(...)` / `add_task_comment(...)` / `log_task_time(...)` — mutate
-
-<!-- TOOLKIT:jira-rules END -->
+1. `sync_tasks(jql="assignee=currentUser() AND status!=Done")` -- fetch fresh
+2. `read_cached_tasks()` -- work offline
+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 (built-in)
+
+| ID | Use for |
+|----|---------|
+| `status-update` | Progress report with completed/next/blockers |
+| `blocker-notification` | Escalate blocking issue |
+| `handoff-transition` | Task handoff between people |
+| `review-request` | Request code review |
+| `sprint-update` | Sprint progress report |
+| `bug-report` | Structured bug report |
+| `deployment-note` | Deployment documentation |
+| `time-log-summary` | Time logging with description |
+
+## CLI Commands
+
+| Command | Description |
+|---------|-------------|
+| `jira-mcp config init` | Initialize global config (~/.softspark/jira-mcp/) |
+| `jira-mcp config add-project <key> <url>` | Add Jira project mapping |
+| `jira-mcp config remove-project <key>` | Remove a project |
+| `jira-mcp config list-projects` | Show configured projects with language |
+| `jira-mcp config set-default <key>` | Set default project |
+| `jira-mcp config set-credentials` | Set API credentials |
+| `jira-mcp config set-language <lang>` | Set global default language |
+| `jira-mcp config set-project-language <key> <lang>` | Set language for a specific project |
+| `jira-mcp create <path>` | Create tasks from template (dry-run default) |
+| `jira-mcp create-monthly` | Create monthly admin tasks |
+| `jira-mcp cache sync-users` | Cache user list for reassignment |
+| `jira-mcp cache sync-workflows` | Cache status transitions |
+| `jira-mcp cache list-users` | Show cached users |
+| `jira-mcp cache list-workflows` | Show cached workflows |
+
+## Architecture
+
+Four layers -- each depends only on layers below:
+
+1. **Types & Config** (`config/`, `errors/`, `*/types.ts`) -- pure data, zero runtime deps
+2. **Infrastructure** (`connector/`, `cache/`, `adf/`, `templates/`) -- I/O and external APIs
+3. **Business Logic** (`operations/`, `bulk/`) -- orchestrates infrastructure
+4. **Entry Points** (`tools/`, `cli/`, `server.ts`) -- thin dispatchers
+
+## Coding Conventions
+
+- **Strict TypeScript**: `strict: true`, NO `any`, `readonly` interfaces, `import type`, `.js` imports
+- **Zod schemas** for all external data: `type Foo = z.infer<typeof FooSchema>`
+- **Error classes**: extend `JiraMcpError` with `code` property
+- **ADF round-trip**: `markdownToAdf()` for writes, `adfToMarkdown()` for reads -- NEVER throw
+- **InstancePool**: singleton, lazy connectors, dedup by URL
+- **Dual-write**: after Jira mutation, update local cache, return API result
+- **Dry-run default**: `--execute` required for destructive operations
+- **DI pattern**: handlers accept `deps?` parameter for testing
+- **Config path**: ALWAYS `~/.softspark/jira-mcp/` via `GLOBAL_CONFIG_DIR` -- no manual config, no env vars in MCP client setup
+- **SoftSpark standard**: all open-source tools use `~/.softspark/<tool-name>/` -- see SOP in rag-mcp `kb/procedures/softspark-config-standard.md`
+
+## Testing
+
+- **Vitest**: 70% coverage threshold, `vi.fn()` for mocks
+- **No real Jira API calls** in tests, use `tests/fixtures/mocks.ts`
+- **Filesystem tests**: `os.tmpdir()` + `mkdtemp()`, NEVER write to `~/.softspark/`
+- Quick pre-commit: `npm run typecheck && npm run lint && npm test && npm run build`
+
+## KB & SOPs
+
+- `kb/reference/` -- architecture, api, configuration, adf, caching, templates
+- `kb/howto/` -- setup, multi-instance, cli-usage
+- `kb/procedures/` -- sop-pre-commit, sop-release, sop-post-release-testing
+
+<!-- TOOLKIT:jira-mcp END -->
 
 <!-- TOOLKIT:rag-mcp-rules START -->
 <!-- Auto-injected by ai-toolkit. Re-run to update. -->

package/CHANGELOG.md

@@ -7,6 +7,32 @@ Versioning follows [Semantic Versioning](https://semver.org/).
 
 ---
 
+## 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
+- **URL rule registration** — `ai-toolkit add-rule https://...` registers rules from HTTPS URLs. URL-sourced rules are tracked in `rules/sources.json` and auto-refreshed on every `ai-toolkit update`. Falls back to cached local copy on network failure.
+- **Version consistency validation** — `validate.py --strict` now cross-checks `package.json`, `manifest.json`, and `plugin.json` versions match
+
+### Fixed
+- **Project registry race condition** — parallel `install --local` during `ai-toolkit update` could silently drop registry entries. Fixed with `fcntl.flock` exclusive lock, atomic writes (tempfile + rename), and deferred sequential registration after parallel phase.
+- **Version drift** — `manifest.json` and `plugin.json` were stuck at 1.9.0 since v2.0.0, now synced
+- **Language rules count** — ARCHITECTURE.md claimed 70 files, actual is 68
+- **Skills catalog tiers** — added missing Tier 1.5 (planning pipeline + design/architecture)
+
+---
+
 ## v2.1.3 — Idempotent Update Fix (2026-04-13)
 
 ### Fixed

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-92-brightgreen)](app/skills/)
 [![Agents](https://img.shields.io/badge/agents-44-blue)](app/agents/)
-[![Tests](https://img.shields.io/badge/tests-598%20passing-success)](tests/)
+[![Tests](https://img.shields.io/badge/tests-606%20passing-success)](tests/)
 
 ---
 
@@ -142,7 +142,7 @@ ai-toolkit/
 │   └── ARCHITECTURE.md  # Full system design
 ├── kb/                  # Reference docs, procedures, plans
 ├── scripts/             # Validation, install, evaluation scripts
-├── tests/               # Bats test suite (598 tests)
+├── tests/               # Bats test suite (606 tests)
 └── CHANGELOG.md
 ```
 
@@ -174,7 +174,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": "1.9.0",
+  "version": "2.3.0",
   "author": {
     "name": "SoftSpark",
     "url": "https://github.com/softspark"

package/app/ARCHITECTURE.md

@@ -302,9 +302,9 @@ 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 (70 files, 13 languages)
+### 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>`.
 
 Language rules are propagated to **all configured editors** — not just Claude. `dir_rules_shared.build_language_rules()` reads `app/rules/<lang>/*.md`, strips frontmatter, and returns combined content per language. Each directory-based generator (Cursor, Windsurf, Cline, Roo, Augment, Antigravity, Codex) emits `ai-toolkit-lang-<lang>` files in its native format. Registered custom rules (`~/.softspark/ai-toolkit/rules/`) are similarly propagated as `ai-toolkit-custom-<name>` files via `build_registered_rules()`.

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/bin/ai-toolkit.js

@@ -63,7 +63,7 @@ const COMMANDS = {
   status: 'Show installed modules, version, and profile from state.json',
   reset: 'Wipe and recreate project-local configs from scratch (requires --local)',
   uninstall: 'Remove ai-toolkit from ~/.claude/',
-  'add-rule': 'Register a rule file in ~/.softspark/ai-toolkit/rules/ (applied on every install/update)',
+  'add-rule': 'Register a rule file or URL in ~/.softspark/ai-toolkit/rules/ (URL rules auto-refresh on update)',
   'remove-rule': 'Unregister a rule from ~/.softspark/ai-toolkit/rules/ and remove its block from CLAUDE.md',
   'inject-hook': 'Inject external hooks into ~/.claude/settings.json (tagged with _source for idempotent updates)',
   'remove-hook': 'Remove injected hooks by source name from ~/.claude/settings.json',
@@ -232,8 +232,8 @@ function showHelp() {
   console.log('  <source-name>   Source tag to remove (derived from hooks filename stem)');
   console.log('  [target-dir]    Target dir containing .claude/settings.json (default: $HOME)');
   console.log('\nOptions for add-rule:');
-  console.log('  <rule-file>     Path to .md rule file to register globally');
-  console.log('  [rule-name]     Override rule name (default: filename without .md)');
+  console.log('  <rule-file>     Path to .md rule file or HTTPS URL to register globally');
+  console.log('  [rule-name]     Override rule name (default: filename/URL stem without .md)');
   console.log('\nOptions for plugin:');
   console.log('  install <name>  Install a plugin pack (--editor claude|codex|all)');
   console.log('  install --all   Install all available plugin packs for selected editor(s)');
@@ -333,16 +333,18 @@ function handleRemoveRule(args) {
 }
 
 /**
- * Handle `ai-toolkit add-rule` -- validates rule file, resolves absolute path.
+ * Handle `ai-toolkit add-rule` -- validates rule file/URL, resolves absolute path.
  * @param {string[]} args
  */
 function handleAddRule(args) {
   const ruleFile = args[0];
   if (!ruleFile) {
-    console.error('Usage: ai-toolkit add-rule <rule-file> [rule-name]');
+    console.error('Usage: ai-toolkit add-rule <rule-file-or-url> [rule-name]');
     process.exit(1);
   }
-  const absRuleFile = path.resolve(CWD, ruleFile);
+  // Pass URLs through directly (don't resolve as filesystem path)
+  const isUrl = ruleFile.startsWith('https://') || ruleFile.startsWith('http://');
+  const absRuleFile = isUrl ? ruleFile : path.resolve(CWD, ruleFile);
   const ruleName = args[1];
   run(scriptPath('add_rule.py'), ruleName ? [absRuleFile, ruleName] : [absRuleFile]);
 }

package/kb/procedures/maintenance-sop.md

@@ -319,6 +319,7 @@ Follow this sequence before every `npm publish` / `git tag`:
 
 ```bash
 # Edit package.json version field (semver: X.Y.Z)
+# Sync package-lock.json: npm install --package-lock-only
 # Add entry to CHANGELOG.md
 ```
 

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

@@ -108,8 +108,9 @@ The canonical version lives in `package.json`. These files **must** match:
 | `README.md` | Badge counts, "What You Get" table |
 | `app/ARCHITECTURE.md` | Section headings with counts |
 
-> **Tip:** `validate.py --strict` and `npm test` (metadata contract tests) catch
-> count drift automatically. If tests pass, counts are correct.
+> **Tip:** `validate.py --strict` catches count drift AND version mismatches
+> (package.json vs manifest.json vs plugin.json) automatically.
+> If validation passes, counts and versions are correct.
 
 ### Verification command
 

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/kb/reference/skills-catalog.md

@@ -17,7 +17,9 @@ All functionality is unified under skills. Task and hybrid skills are user-invoc
 
 | Tier | Skills | When |
 |------|--------|------|
-| **1 — Quick single-agent** | `/debug`, `/review`, `/refactor`, `/analyze`, `/docs`, `/plan`, `/explain` | One concern, fast |
+| **1 — Quick single-agent** | `/debug`, `/review`, `/refactor`, `/analyze`, `/docs`, `/plan`, `/explain`, `/tdd`, `/grill-me`, `/triage-issue` | One concern, fast |
+| **1.5 — Product planning** | `/write-a-prd` → `/prd-to-plan` → `/prd-to-issues` | Interview-driven PRD → vertical-slice plan → GitHub issues |
+| **1.5 — Design & architecture** | `/design-an-interface`, `/architecture-audit`, `/refactor-plan`, `/ubiquitous-language`, `/qa-session` | Parallel sub-agent exploration |
 | **2 — Multi-agent workflow** | `/workflow <type>` | Cross-cutting task with known pattern |
 | **3 — Custom parallelism** | `/orchestrate`, `/swarm` | No predefined workflow matches |
 

package/llms-full.txt

@@ -3441,6 +3441,7 @@ Follow this sequence before every `npm publish` / `git tag`:
 
 ```bash
 # Edit package.json version field (semver: X.Y.Z)
+# Sync package-lock.json: npm install --package-lock-only
 # Add entry to CHANGELOG.md
 ```
 
@@ -3619,8 +3620,9 @@ The canonical version lives in `package.json`. These files **must** match:
 | `README.md` | Badge counts, "What You Get" table |
 | `app/ARCHITECTURE.md` | Section headings with counts |
 
-> **Tip:** `validate.py --strict` and `npm test` (metadata contract tests) catch
-> count drift automatically. If tests pass, counts are correct.
+> **Tip:** `validate.py --strict` catches count drift AND version mismatches
+> (package.json vs manifest.json vs plugin.json) automatically.
+> If validation passes, counts and versions are correct.
 
 ### Verification command
 
@@ -4772,7 +4774,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.
@@ -5162,7 +5164,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 |
@@ -7812,7 +7814,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
 
@@ -8016,14 +8018,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
 
@@ -8518,7 +8520,9 @@ All functionality is unified under skills. Task and hybrid skills are user-invoc
 
 | Tier | Skills | When |
 |------|--------|------|
-| **1 — Quick single-agent** | `/debug`, `/review`, `/refactor`, `/analyze`, `/docs`, `/plan`, `/explain` | One concern, fast |
+| **1 — Quick single-agent** | `/debug`, `/review`, `/refactor`, `/analyze`, `/docs`, `/plan`, `/explain`, `/tdd`, `/grill-me`, `/triage-issue` | One concern, fast |
+| **1.5 — Product planning** | `/write-a-prd` → `/prd-to-plan` → `/prd-to-issues` | Interview-driven PRD → vertical-slice plan → GitHub issues |
+| **1.5 — Design & architecture** | `/design-an-interface`, `/architecture-audit`, `/refactor-plan`, `/ubiquitous-language`, `/qa-session` | Parallel sub-agent exploration |
 | **2 — Multi-agent workflow** | `/workflow <type>` | Cross-cutting task with known pattern |
 | **3 — Custom parallelism** | `/orchestrate`, `/swarm` | No predefined workflow matches |
 

package/manifest.json

@@ -1,5 +1,5 @@
 {
-  "version": "1.9.0",
+  "version": "2.3.0",
   "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.1.3",
+  "version": "2.3.0",
   "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/add_rule.py

@@ -1,52 +1,94 @@
 #!/usr/bin/env python3
-"""add-rule -- Register a rule file in ~/.softspark/ai-toolkit/rules/.
+"""add-rule -- Register a rule file or URL in ~/.softspark/ai-toolkit/rules/.
 
 Registered rules are automatically injected into all AI tool configs
-on next 'ai-toolkit install' or 'ai-toolkit update':
+on next 'ai-toolkit install' or 'ai-toolkit update'.
+URL-sourced rules are auto-refreshed on every update.
+
   Global: Claude, Cursor, Windsurf, Gemini, Augment
   Local (--local): all of the above + Copilot, Cline, Roo, Aider, Antigravity
 
 Usage:
-  add_rule.py <rule-file> [rule-name]
+  add_rule.py <rule-file-or-url> [rule-name]
 
 Arguments:
-  rule-file   Path to .md file with the rule content
-  rule-name   Override the rule name (default: filename without .md)
+  rule-file-or-url  Path to .md file or HTTPS URL to register globally
+  rule-name         Override the rule name (default: filename without .md)
 """
 from __future__ import annotations
 
 import re
 import shutil
 import sys
+import urllib.parse
 from pathlib import Path
 
 sys.path.insert(0, str(Path(__file__).resolve().parent))
 
 
+def _name_from_url(url: str) -> str:
+    """Derive a rule name from a URL's last path segment."""
+    parsed = urllib.parse.urlparse(url)
+    filename = parsed.path.rstrip("/").split("/")[-1]
+    stem = filename.rsplit(".", 1)[0] if "." in filename else filename
+    return re.sub(r"[^a-zA-Z0-9_-]", "", stem)
+
+
 def main() -> None:
-    """Register a rule file in the global rules directory."""
+    """Register a rule file or URL in the global rules directory."""
     if len(sys.argv) < 2:
-        print("Usage: add_rule.py <rule-file> [rule-name]", file=sys.stderr)
+        print("Usage: add_rule.py <rule-file-or-url> [rule-name]", file=sys.stderr)
         sys.exit(1)
 
-    rule_file = Path(sys.argv[1])
-    if not rule_file.is_file():
-        print(f"Rule file not found: {rule_file}", file=sys.stderr)
-        sys.exit(1)
+    source = sys.argv[1]
+    is_url = source.startswith("https://") or source.startswith("http://")
 
-    rule_name = sys.argv[2] if len(sys.argv) > 2 else rule_file.stem
-    rule_name = re.sub(r"[^a-zA-Z0-9_-]", "", rule_name)
-    if not rule_name:
-        print("Error: rule name is empty after sanitization", file=sys.stderr)
+    if is_url and source.startswith("http://"):
+        print("Error: only HTTPS URLs are supported. Use https:// for security.", file=sys.stderr)
         sys.exit(1)
+
     from paths import RULES_DIR
     rules_dir = RULES_DIR
     rules_dir.mkdir(parents=True, exist_ok=True)
 
-    dest = rules_dir / f"{rule_name}.md"
-    shutil.copy2(rule_file, dest)
+    if is_url:
+        from rule_sources import fetch_url, register_url_source
+
+        rule_name = sys.argv[2] if len(sys.argv) > 2 else _name_from_url(source)
+        rule_name = re.sub(r"[^a-zA-Z0-9_-]", "", rule_name)
+        if not rule_name:
+            print("Error: could not derive rule name from URL. Provide one explicitly.", file=sys.stderr)
+            sys.exit(1)
+
+        try:
+            data = fetch_url(source)
+        except Exception as exc:
+            print(f"Error fetching URL: {exc}", file=sys.stderr)
+            sys.exit(1)
+
+        dest = rules_dir / f"{rule_name}.md"
+        dest.write_bytes(data)
+        register_url_source(rules_dir, rule_name, source)
+
+        print(f"Registered: '{rule_name}' -> {dest}")
+        print(f"Source URL: {source} (auto-refreshed on update)")
+    else:
+        rule_file = Path(source)
+        if not rule_file.is_file():
+            print(f"Rule file not found: {rule_file}", file=sys.stderr)
+            sys.exit(1)
+
+        rule_name = sys.argv[2] if len(sys.argv) > 2 else rule_file.stem
+        rule_name = re.sub(r"[^a-zA-Z0-9_-]", "", rule_name)
+        if not rule_name:
+            print("Error: rule name is empty after sanitization", file=sys.stderr)
+            sys.exit(1)
+
+        dest = rules_dir / f"{rule_name}.md"
+        shutil.copy2(rule_file, dest)
+
+        print(f"Registered: '{rule_name}' -> {dest}")
 
-    print(f"Registered: '{rule_name}' -> {dest}")
     print()
     print("Apply now:")
     print("  ai-toolkit update            # global (Claude, Cursor, Windsurf, Gemini, Augment)")

package/scripts/install.py

@@ -212,6 +212,7 @@ def parse_args(argv: list[str]) -> dict:
         "editors": "",
         "config": "",
         "refresh_base": False,
+        "skip_register": False,
     }
     i = 0
     while i < len(argv):
@@ -268,6 +269,8 @@ def parse_args(argv: list[str]) -> dict:
             cfg["config"] = argv[i] if i < len(argv) else ""
         elif arg == "--refresh-base":
             cfg["refresh_base"] = True
+        elif arg == "--skip-register":
+            cfg["skip_register"] = True
         elif arg.startswith("-"):
             print(f"Unknown option: {arg}")
             sys.exit(1)
@@ -426,7 +429,40 @@ def install_claude_code(target_dir: Path, hooks_scripts_dir: Path,
     print()
     print(f"  Available: {count_agents()} agents, {count_skills()} skills")
 
-    inject_rules(claude_dir, target_dir, rules_dir, only, skip, dry_run)
+    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")
@@ -711,7 +747,9 @@ def main() -> None:
         )
 
         # Register project in global registry (for `ai-toolkit update` propagation)
-        if local:
+        # Skipped when called from update_projects.py (--skip-register) to avoid
+        # concurrent writes to projects.json during parallel updates.
+        if local and not cfg.get("skip_register"):
             extends_source = ""
             if extends_info:
                 extends_source = extends_info.get("source", "")