@softspark/ai-toolkit 1.3.10 → 1.3.11

package/CHANGELOG.md

@@ -7,6 +7,21 @@ Versioning follows [Semantic Versioning](https://semver.org/).
 
 ---
 
+## v1.3.11 — Proactive Context Checkpointing + Augment CLI (2026-04-08)
+
+### Added
+- **Constitution Art. I §5: Proactive Context Checkpointing** — agents must checkpoint `.claude/session-context.md` during multi-step tasks (objective, completed/pending steps, files modified, key decisions).
+- **`augment-rules` CLI command** — wired `generate_augment.py` into `bin/ai-toolkit.js` GENERATORS + COMMANDS + `generate-all`. Generates `.augment/rules/ai-toolkit.md`.
+- **Augment in Platform Support** — added to README table with project scope.
+
+### Changed
+- **`save-session.sh`** — enriched with git branch, dirty count, diff stat, and agent-written checkpoint preservation.
+- **Language rules count** — corrected 70→68 in README.md (13 dirs × 5 + 3 standalone).
+- **Secondary docs** — removed hardcoded rule counts from `language-rules.md`, `architecture-overview.md`, `competitive-features-implementation.md`; reference README for canonical count.
+- **README architecture tree** — added missing `track-usage.sh`.
+
+---
+
 ## v1.3.10 — Patch (2026-04-07)
 
 ### Fixed

package/README.md

@@ -122,6 +122,7 @@ Replaces all symlinks with real files, inlines rules into CLAUDE.md, copies cons
 | Cline | `.clinerules` | `ai-toolkit install --local` | project |
 | Roo Code | `.roomodes` | `ai-toolkit install --local` | project |
 | Aider | `.aider.conf.yml` | `ai-toolkit install --local` | project |
+| Augment | `.augment/rules/ai-toolkit.md` | `ai-toolkit install --local` | project |
 | Codex / OpenCode | `AGENTS.md` | `ai-toolkit agents-md` | project |
 
 > **Note:** Claude Code remains the primary platform with full feature support (agents, lifecycle hooks, safety constitution). Other platforms receive a distilled ruleset generated from the same source. For editors lacking native bash lifecycle hooks, `--local` installs a Git hooks fallback (`.git/hooks/pre-commit`) to enforce quality gates pre-commit.
@@ -179,7 +180,8 @@ ai-toolkit/
 │   │   ├── mcp-health.sh         # MCP server availability check
 │   │   ├── governance-capture.sh # Security-sensitive op logging
 │   │   ├── commit-quality.sh     # Conventional commit advisory
-│   │   └── session-context.sh    # Environment snapshot on start
+│   │   ├── session-context.sh    # Environment snapshot on start
+│   │   └── track-usage.sh        # Skill invocation tracking
 │   ├── hooks.json       # Hook definitions (merged into settings.json)
 │   ├── plugins/         # Experimental plugin packs (opt-in, not part of default install)
 │   ├── output-styles/   # System prompt output style overrides
@@ -471,7 +473,7 @@ Templates include: GitHub, PostgreSQL, Slack, Sentry, Context7, Brave Search, Su
 
 ## Language Rules
 
-70 language-specific coding rules across 13 languages: TypeScript, Python, Go, Rust, Java, Kotlin, Swift, Dart, C#, PHP, C++, Ruby, plus 5 common rules. Each language has 5 rule categories: coding-style, testing, patterns, frameworks, security.
+68 language-specific coding rules across 13 languages: TypeScript, Python, Go, Rust, Java, Kotlin, Swift, Dart, C#, PHP, C++, Ruby, plus common rules. Each language has 5 rule categories: coding-style, testing, patterns, frameworks, security.
 
 ```bash
 ai-toolkit install --local                   # auto-detects project language, installs matching rules

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

package/app/constitution.md

@@ -20,6 +20,13 @@ status: IMMUTABLE
 - All iterations MUST be logged to stats for audit
 - Exceeding limits requires explicit user override
 
+### Section 5: Proactive Context Checkpointing
+- During multi-step tasks (>5 tool calls), update `.claude/session-context.md` after each major milestone
+- Checkpoint MUST include: current objective, completed steps, pending steps, files modified, key decisions
+- Minimum frequency: after every completed task phase, workflow stage, or subagent handoff
+- Agent SHOULD checkpoint before any risky or destructive operation
+- Format: append `## Checkpoint <timestamp>` sections, do not overwrite previous checkpoints within the same session
+
 ## Article II: The Hierarchy of Truth
 1. **KB Supremacy**: The Knowledge Base (`kb/`) is the source of truth. If code contradicts KB, check KB freshness.
 2. **Research Protocol**: Use `research-mastery` skill before any major decision. Guessing is forbidden.

package/app/hooks/save-session.sh

@@ -16,6 +16,17 @@ SESSION_FILE=".claude/session-context.md"
 
 if [ -n "$SESSION_ID" ]; then
     mkdir -p .claude
+
+    # Gather git state for richer context
+    GIT_BRANCH=""
+    GIT_DIRTY="0"
+    GIT_DIFF_STAT=""
+    if command -v git >/dev/null 2>&1 && git rev-parse --is-inside-work-tree >/dev/null 2>&1; then
+        GIT_BRANCH=$(git branch --show-current 2>/dev/null || echo "detached")
+        GIT_DIRTY=$(git status --porcelain 2>/dev/null | wc -l | tr -d ' ')
+        GIT_DIFF_STAT=$(git diff --stat HEAD 2>/dev/null | tail -5)
+    fi
+
     cat > "$SESSION_FILE" << EOF
 # Session Context
 Updated: $(date -u +"%Y-%m-%dT%H:%M:%SZ")
@@ -23,7 +34,18 @@ Session: ${SESSION_ID}
 
 ## Last Assistant Message
 ${LAST_MSG}
+
+## Git State
+Branch: ${GIT_BRANCH:-N/A}
+Uncommitted changes: ${GIT_DIRTY}
+${GIT_DIFF_STAT:+${GIT_DIFF_STAT}}
 EOF
+
+    # Preserve any agent-written checkpoints (appended by proactive checkpointing)
+    if [ -f "${SESSION_FILE}.checkpoints" ]; then
+        echo "" >> "$SESSION_FILE"
+        cat "${SESSION_FILE}.checkpoints" >> "$SESSION_FILE"
+    fi
 fi
 
 exit 0

package/bin/ai-toolkit.js

@@ -27,6 +27,7 @@ const GENERATORS = {
   'cline-rules':          { script: 'generate_cline.py',         dest: '.clinerules' },
   'roo-modes':            { script: 'generate_roo_modes.py',     dest: '.roomodes' },
   'aider-conf':           { script: 'generate_aider_conf.py',    dest: '.aider.conf.yml' },
+  'augment-rules':        { script: 'generate_augment.py',       dest: path.join('.augment', 'rules', 'ai-toolkit.md'), mkdir: '.augment/rules' },
   'agents-md':            { script: 'generate_agents_md.py',     dest: 'AGENTS.md' },
 };
 
@@ -82,9 +83,10 @@ const COMMANDS = {
   'cline-rules': 'Generate .clinerules for Cline',
   'roo-modes': 'Generate .roomodes for Roo Code',
   'aider-conf': 'Generate .aider.conf.yml for Aider',
+  'augment-rules': 'Generate .augment/rules/ai-toolkit.md for Augment',
   'agents-md': 'Regenerate AGENTS.md from agent definitions',
   'llms-txt': 'Generate llms.txt and llms-full.txt',
-  'generate-all': 'Generate all platform configs at once (agents, cursor, windsurf, copilot, gemini, cline, roo, aider, llms)',
+  'generate-all': 'Generate all platform configs at once (agents, cursor, windsurf, copilot, gemini, cline, roo, aider, augment, llms)',
   help: 'Show this help message',
 };
 

package/kb/reference/architecture-overview.md

@@ -269,7 +269,7 @@ Severity levels: HIGH (blocks deployment), WARN (should fix), INFO (best practic
 `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`.
 
 ### Language Rules
-`app/rules/` provides 70 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>`.
+`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.
 
 ### Extension API (`inject-hook`)
 `inject_section_cli.py` provides a stable marker-based API for injecting content into `CLAUDE.md`, `constitution.md`, or `ARCHITECTURE.md` without overwriting user content.

package/kb/reference/competitive-features-implementation.md

@@ -35,7 +35,7 @@ Strengthen ai-toolkit's competitive position by implementing 10 features from co
 **Key design principle:** ai-toolkit is a **generic toolkit** — it does NOT know about rag-mcp or any specific consumer. Consumers (like rag-mcp) use ai-toolkit's public API (`inject-rule`, `inject-hook`, `merge-hooks`) to add their own rules and hooks.
 
 **State before plan:** 88 skills, 47 agents, 14 hooks, 9 editor integrations
-**State after plan:** See manifest.json for current counts. Target: skills, agents, hooks, 70 language rules, 25 MCP templates, extension API
+**State after plan:** See manifest.json and README.md for current counts. Target: skills, agents, hooks, language rules, MCP templates, extension API
 
 ---
 
@@ -641,7 +641,7 @@ npx @softspark/ai-toolkit inject-hook  ./rag-mcp-hooks.json    # NEW
 
 | Risk | Probability | Impact | Mitigation |
 |------|-------------|--------|------------|
-| 70 rule files = maintenance burden | Medium | Medium | Auto-generate from ECC (port script), validate.py checks |
+| Rule files = maintenance burden | Medium | Medium | Auto-generate from ECC (port script), validate.py checks |
 | inject-hook misuse by consumers | Low | Medium | Validate JSON schema, reject malformed hooks |
 | Manifest install breaks existing | Low | High | Backward compatible, existing CLI preserved |
 | Documentation site drift | Medium | Medium | Generate from source (CLAUDE.md → site), CI check |

package/kb/reference/hooks-catalog.md

@@ -147,7 +147,10 @@ Skipped when `TOOLKIT_HOOK_PROFILE=minimal`.
 | Script | `~/.ai-toolkit/hooks/save-session.sh` |
 | Fires | After every Claude response |
 
-**Action:** Writes session context to `.claude/session-context.md` for cross-session persistence.
+**Action:** Writes enriched session context to `.claude/session-context.md` for cross-session persistence. Captures:
+- Session ID and last assistant message (first 5 lines)
+- Git branch, uncommitted change count, and diff stat (last 5 lines)
+- Agent-written checkpoints from `.claude/session-context.md.checkpoints` (if present — written by proactive checkpointing per Constitution Art. I §5)
 
 Skipped when `TOOLKIT_HOOK_PROFILE=minimal`.
 

package/kb/reference/language-rules.md

@@ -13,7 +13,7 @@ description: "Reference for the language-specific rules system: 13 languages, 5
 
 ## Overview
 
-ai-toolkit ships 70 language-specific rule files covering 13 programming languages plus a common set. Rules are plain Markdown files injected into `CLAUDE.md` via `ai-toolkit install --local`. They provide coding-style, testing, patterns, frameworks, and security guidance specific to each language.
+ai-toolkit ships language-specific rule files covering 13 programming languages plus a common set (see README.md for current count). Rules are plain Markdown files injected into `CLAUDE.md` via `ai-toolkit install --local`. They provide coding-style, testing, patterns, frameworks, and security guidance specific to each language.
 
 Rules are distinct from skills: rules are injected as static text into `CLAUDE.md` and are always visible to Claude, whereas skills are loaded contextually by agents.
 
@@ -51,7 +51,7 @@ app/rules/
 └── ruby/
 ```
 
-**Total: 13 languages × 5 files + 5 common = 70 rule files**
+**Total: 13 directories × 5 files each + 3 standalone = 68 rule files** (see README.md for canonical count)
 
 ## Supported Languages
 

package/llms-full.txt

@@ -1199,7 +1199,7 @@ Severity levels: HIGH (blocks deployment), WARN (should fix), INFO (best practic
 `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`.
 
 ### Language Rules
-`app/rules/` provides 70 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>`.
+`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.
 
 ### Extension API (`inject-hook`)
 `inject_section_cli.py` provides a stable marker-based API for injecting content into `CLAUDE.md`, `constitution.md`, or `ARCHITECTURE.md` without overwriting user content.
@@ -1578,7 +1578,7 @@ Strengthen ai-toolkit's competitive position by implementing 10 features from co
 **Key design principle:** ai-toolkit is a **generic toolkit** — it does NOT know about rag-mcp or any specific consumer. Consumers (like rag-mcp) use ai-toolkit's public API (`inject-rule`, `inject-hook`, `merge-hooks`) to add their own rules and hooks.
 
 **State before plan:** 88 skills, 47 agents, 14 hooks, 9 editor integrations
-**State after plan:** See manifest.json for current counts. Target: skills, agents, hooks, 70 language rules, 25 MCP templates, extension API
+**State after plan:** See manifest.json and README.md for current counts. Target: skills, agents, hooks, language rules, MCP templates, extension API
 
 ---
 
@@ -2184,7 +2184,7 @@ npx @softspark/ai-toolkit inject-hook  ./rag-mcp-hooks.json    # NEW
 
 | Risk | Probability | Impact | Mitigation |
 |------|-------------|--------|------------|
-| 70 rule files = maintenance burden | Medium | Medium | Auto-generate from ECC (port script), validate.py checks |
+| Rule files = maintenance burden | Medium | Medium | Auto-generate from ECC (port script), validate.py checks |
 | inject-hook misuse by consumers | Low | Medium | Validate JSON schema, reject malformed hooks |
 | Manifest install breaks existing | Low | High | Backward compatible, existing CLI preserved |
 | Documentation site drift | Medium | Medium | Generate from source (CLAUDE.md → site), CI check |
@@ -2886,7 +2886,10 @@ Skipped when `TOOLKIT_HOOK_PROFILE=minimal`.
 | Script | `~/.ai-toolkit/hooks/save-session.sh` |
 | Fires | After every Claude response |
 
-**Action:** Writes session context to `.claude/session-context.md` for cross-session persistence.
+**Action:** Writes enriched session context to `.claude/session-context.md` for cross-session persistence. Captures:
+- Session ID and last assistant message (first 5 lines)
+- Git branch, uncommitted change count, and diff stat (last 5 lines)
+- Agent-written checkpoints from `.claude/session-context.md.checkpoints` (if present — written by proactive checkpointing per Constitution Art. I §5)
 
 Skipped when `TOOLKIT_HOOK_PROFILE=minimal`.
 
@@ -3291,7 +3294,7 @@ description: "Reference for the language-specific rules system: 13 languages, 5
 
 ## Overview
 
-ai-toolkit ships 70 language-specific rule files covering 13 programming languages plus a common set. Rules are plain Markdown files injected into `CLAUDE.md` via `ai-toolkit install --local`. They provide coding-style, testing, patterns, frameworks, and security guidance specific to each language.
+ai-toolkit ships language-specific rule files covering 13 programming languages plus a common set (see README.md for current count). Rules are plain Markdown files injected into `CLAUDE.md` via `ai-toolkit install --local`. They provide coding-style, testing, patterns, frameworks, and security guidance specific to each language.
 
 Rules are distinct from skills: rules are injected as static text into `CLAUDE.md` and are always visible to Claude, whereas skills are loaded contextually by agents.
 
@@ -3329,7 +3332,7 @@ app/rules/
 └── ruby/
 ```
 
-**Total: 13 languages × 5 files + 5 common = 70 rule files**
+**Total: 13 directories × 5 files each + 3 standalone = 68 rule files** (see README.md for canonical count)
 
 ## Supported Languages
 

package/manifest.json

@@ -1,5 +1,5 @@
 {
-  "version": "1.3.10",
+  "version": "1.3.11",
   "components": {
     "agents": {
       "description": "44 specialized agents (orchestrator, backend, frontend, security, devops, etc.)",

package/package.json

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