@softspark/ai-toolkit 2.1.1 → 2.1.2

package/AGENTS.md

@@ -386,3 +386,50 @@ Testing expert. Use for writing tests (unit, integration, e2e), TDD workflow, te
 
 ---
 
+<!-- TOOLKIT:jira-rules 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`
+
+## Key Rules
+
+- **Always `sync_tasks` first** before reading — cache may be stale.
+- **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).
+
+## 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 -->
+<!-- TOOLKIT:rag-mcp-rules START -->
+<!-- Auto-injected by ai-toolkit. Re-run to update. -->
+
+## INSTANT ACTION RULE (GOLDEN RULE)
+
+**ANY technical question? -> INSTANTLY call `smart_query()` OR `hybrid_search_kb()` BEFORE outputting text!**
+
+1. **Search First:** `smart_query()` or `hybrid_search_kb()` (NEVER skip, even if you "know").
+2. **Cite Sources:** always include `[PATH: kb/...]`.
+3. **Strict Order:** Semantic Search -> Files -> External Docs -> General Knowledge.
+
+Default tool: `smart_query()`. Use `hybrid_search_kb()` for speed, `crag_search()` for vague queries, `multi_hop_search()` for complex reasoning.
+
+## kb_id vs file_path
+
+- `get_document(path=...)` takes `kb_id` from search results (e.g., `local/softspark/project/reference/api.md`)
+- `Read`/`Edit` take filesystem `file_path` (e.g., `./reference/api.md`)
+- **DO NOT CONFUSE** these fields.
+
+## SOPs
+
+ALWAYS check `kb/procedures/` first: `smart_query("SOP for <task>")`.
+
+<!-- TOOLKIT:rag-mcp-rules END -->
+

package/CHANGELOG.md

@@ -7,6 +7,13 @@ Versioning follows [Semantic Versioning](https://semver.org/).
 
 ---
 
+## v2.1.2 — Idempotent Update Fix (2026-04-13)
+
+### Fixed
+- **`ai-toolkit update` no longer dirties git** — generators now skip custom rule emission when called by `inject_with_rules()` (which handles injection separately). Previously, `update` caused AGENTS.md and other generated files to gain extra blank lines on every run.
+
+---
+
 ## v2.1.1 — Custom Rules in Generators & README Restructure (2026-04-13)
 
 ### Fixed

package/README.md

@@ -10,12 +10,12 @@
 
 ---
 
-## What's New in v2.1.1
+## What's New in v2.1.2
 
-- **Custom rules in generators** — `generate:all` now preserves registered rules from other repos across all platforms
-- **README restructured** — 951 → 292 lines with TOC, "What's New" section, and links to KB docs
-- **CLI help completeness** — added missing `--persona` option and `codex` to `--editors`
-- **3 new KB docs** — CLI Reference, Unique Features, Ecosystem Comparison (moved from README)
+- **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
 
 See [CHANGELOG.md](CHANGELOG.md) for full history.
 

package/bin/ai-toolkit.js

@@ -405,8 +405,9 @@ function handleConfig(args) {
  */
 function handleGenerateAll(_args) {
   for (const [name, gen] of Object.entries(GENERATORS)) {
-    // Skip agents-md — codex-md generates a superset to the same AGENTS.md
-    if (name === 'agents-md') continue;
+    // Skip codex-md — it injects a Codex config block via markers (used by install --local --editors codex)
+    // agents-md generates the full agent list which is the standalone AGENTS.md
+    if (name === 'codex-md') continue;
     writeGeneratorOutput(gen);
   }
   // Directory-based generators (multi-file output)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@softspark/ai-toolkit",
-  "version": "2.1.1",
+  "version": "2.1.2",
   "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",
@@ -46,7 +46,7 @@
     "evaluate": "python3 scripts/evaluate_skills.py",
     "benchmark:ecosystem": "python3 scripts/benchmark_ecosystem.py --offline",
     "benchmark:harvest": "python3 scripts/harvest_ecosystem.py --offline",
-    "generate:agents": "python3 scripts/generate_codex.py > AGENTS.md",
+    "generate:agents": "python3 scripts/generate_agents_md.py > AGENTS.md",
     "generate:cursor": "python3 scripts/generate_cursor_rules.py > .cursorrules",
     "generate:llms": "python3 scripts/generate_llms_txt.py > llms.txt && python3 scripts/generate_llms_txt.py --full > llms-full.txt",
     "generate:windsurf": "python3 scripts/generate_windsurf.py > .windsurfrules",

package/scripts/generate_agents_md.py

@@ -6,6 +6,7 @@ Usage: ./scripts/generate_agents_md.py > AGENTS.md
 """
 from __future__ import annotations
 
+import os
 import sys
 from pathlib import Path
 
@@ -87,16 +88,17 @@ def main() -> None:
         print("---")
         print()
 
-    # Registered custom rules from ~/.softspark/ai-toolkit/rules/
-    if RULES_DIR.is_dir():
-        for rule_file in sorted(RULES_DIR.glob("*.md")):
-            rule_name = rule_file.stem
-            print(f"<!-- TOOLKIT:{rule_name} START -->")
-            print("<!-- Auto-injected by ai-toolkit. Re-run to update. -->")
-            print()
-            print(rule_file.read_text(encoding="utf-8").rstrip())
-            print()
-            print(f"<!-- TOOLKIT:{rule_name} END -->")
+    # Registered custom rules — skip when called by inject_with_rules()
+    if not os.environ.get("_TOOLKIT_INJECT_MODE"):
+        if RULES_DIR.is_dir():
+            for rule_file in sorted(RULES_DIR.glob("*.md")):
+                rule_name = rule_file.stem
+                print(f"<!-- TOOLKIT:{rule_name} START -->")
+                print("<!-- Auto-injected by ai-toolkit. Re-run to update. -->")
+                print()
+                print(rule_file.read_text(encoding="utf-8").rstrip())
+                print()
+                print(f"<!-- TOOLKIT:{rule_name} END -->")
             print()
 
 

package/scripts/generate_codex.py

@@ -8,6 +8,7 @@ Usage: ./scripts/generate_codex.py > AGENTS.md
 """
 from __future__ import annotations
 
+import os
 import sys
 from pathlib import Path
 
@@ -88,17 +89,19 @@ def main() -> None:
 
     print_toolkit_end()
 
-    # Registered custom rules from ~/.softspark/ai-toolkit/rules/
-    if RULES_DIR.is_dir():
-        for rule_file in sorted(RULES_DIR.glob("*.md")):
-            rule_name = rule_file.stem
-            print()
-            print(f"<!-- TOOLKIT:{rule_name} START -->")
-            print("<!-- Auto-injected by ai-toolkit. Re-run to update. -->")
-            print()
-            print(rule_file.read_text(encoding="utf-8").rstrip())
-            print()
-            print(f"<!-- TOOLKIT:{rule_name} END -->")
+    # Registered custom rules — skip when called by inject_with_rules()
+    # (which handles injection separately via inject_section)
+    if not os.environ.get("_TOOLKIT_INJECT_MODE"):
+        if RULES_DIR.is_dir():
+            for rule_file in sorted(RULES_DIR.glob("*.md")):
+                rule_name = rule_file.stem
+                print()
+                print(f"<!-- TOOLKIT:{rule_name} START -->")
+                print("<!-- Auto-injected by ai-toolkit. Re-run to update. -->")
+                print()
+                print(rule_file.read_text(encoding="utf-8").rstrip())
+                print()
+                print(f"<!-- TOOLKIT:{rule_name} END -->")
 
 
 if __name__ == "__main__":

package/scripts/generator_base.py

@@ -26,6 +26,7 @@ Usage::
 """
 from __future__ import annotations
 
+import os
 import sys
 from pathlib import Path
 
@@ -142,14 +143,15 @@ def render_generator(config: dict) -> None:
         print()
         print_toolkit_end()
 
-    # Registered custom rules from ~/.softspark/ai-toolkit/rules/
-    if RULES_DIR.is_dir():
-        for rule_file in sorted(RULES_DIR.glob("*.md")):
-            rule_name = rule_file.stem
-            print()
-            print(f"<!-- TOOLKIT:{rule_name} START -->")
-            print("<!-- Auto-injected by ai-toolkit. Re-run to update. -->")
-            print()
-            print(rule_file.read_text(encoding="utf-8").rstrip())
-            print()
-            print(f"<!-- TOOLKIT:{rule_name} END -->")
+    # Registered custom rules — skip when called by inject_with_rules()
+    if not os.environ.get("_TOOLKIT_INJECT_MODE"):
+        if RULES_DIR.is_dir():
+            for rule_file in sorted(RULES_DIR.glob("*.md")):
+                rule_name = rule_file.stem
+                print()
+                print(f"<!-- TOOLKIT:{rule_name} START -->")
+                print("<!-- Auto-injected by ai-toolkit. Re-run to update. -->")
+                print()
+                print(rule_file.read_text(encoding="utf-8").rstrip())
+                print()
+                print(f"<!-- TOOLKIT:{rule_name} END -->")

package/scripts/install_steps/ai_tools.py

@@ -1,6 +1,7 @@
 """Install AI tool configs (Cursor, Windsurf, Gemini, Augment, Codex) and local project setup."""
 from __future__ import annotations
 
+import os
 import shutil
 import subprocess
 from pathlib import Path
@@ -78,7 +79,8 @@ def inject_with_rules(
     else:
         cmd = ["bash", str(scripts_dir / generator_script)]
 
-    result = subprocess.run(cmd, capture_output=True, text=True)
+    env = {**os.environ, "_TOOLKIT_INJECT_MODE": "1"}
+    result = subprocess.run(cmd, capture_output=True, text=True, env=env)
     if result.returncode != 0:
         print(f"  ERROR: {generator_script} failed: {result.stderr.strip()}")
         return