@softspark/ai-toolkit 1.0.0 → 1.2.0

package/app/skills/persona/SKILL.md

@@ -0,0 +1,57 @@
+---
+name: persona
+description: "Switch engineering persona at runtime: backend-lead, frontend-lead, devops-eng, junior-dev"
+effort: low
+user-invocable: true
+argument-hint: "[backend-lead | frontend-lead | devops-eng | junior-dev | --list | --clear]"
+allowed-tools: Read, Glob
+---
+
+# /persona - Runtime Persona Switching
+
+$ARGUMENTS
+
+Switch your working persona without re-installing. Personas adjust communication style, preferred skills, and code review priorities for the current session.
+
+## Usage
+
+```
+/persona backend-lead     # Activate backend lead persona
+/persona frontend-lead    # Activate frontend lead persona
+/persona devops-eng       # Activate DevOps engineer persona
+/persona junior-dev       # Activate junior developer persona
+/persona --list           # Show available personas
+/persona --clear          # Reset to default (no persona)
+```
+
+## Available Personas
+
+| Persona | Focus | Preferred Skills |
+|---------|-------|-----------------|
+| `backend-lead` | System design, scalability, data integrity, API stability | `/workflow backend-feature`, `/tdd` |
+| `frontend-lead` | Component architecture, a11y, state management, Core Web Vitals | `/design-an-interface`, `/review` |
+| `devops-eng` | IaC, CI/CD, blast radius, rollback safety, observability | `/workflow infrastructure-change`, `/deploy` |
+| `junior-dev` | Step-by-step explanations, learning resources, small PRs | `/explain`, `/explore`, `/debug` |
+
+## Steps
+
+1. Parse `$ARGUMENTS`
+2. If `--list`: read all `app/personas/*.md` files via Glob, display table with name and first-line summary
+3. If `--clear`: respond with "Persona cleared. Using default behavior for the rest of this session."
+4. If persona name given:
+   a. Read the persona file from `app/personas/{name}.md` (relative to toolkit root)
+   b. If file not found, try the installed location: `~/.claude/skills/persona/../../../app/personas/{name}.md`
+   c. Display the persona content to Claude
+   d. State: "**Persona active: {name}**. I will follow these guidelines for the rest of this session."
+5. If no argument: show usage and available personas
+
+## How It Works
+
+Unlike `--persona` at install time (which injects into CLAUDE.md permanently), `/persona` applies for the **current session only**. The persona file content is loaded into the conversation context and Claude follows it until the session ends or `/persona --clear` is called.
+
+## Rules
+
+- This skill is READ-ONLY — it never writes files
+- Persona stays active for the current session only
+- Only one persona active at a time — switching replaces the previous one
+- Valid personas are defined by `.md` files in `app/personas/`

package/app/skills/plan-writing/SKILL.md

@@ -3,6 +3,7 @@ name: plan-writing
 description: "Loaded when user asks to write an implementation plan or pre-mortem"
 effort: medium
 user-invocable: false
+allowed-tools: Read
 ---
 
 # Plan Writing Skill

package/app/skills/pr/scripts/pr-summary.py

@@ -36,15 +36,18 @@ CONVENTIONAL_TYPES: dict[str, str] = {
 
 
 def run(cmd: str) -> str:
-    """Run a shell command and return stripped stdout.
+    """Run a command and return stripped stdout.
 
     Args:
-        cmd: Shell command string to execute.
+        cmd: Command string (split via shlex, no shell).
 
     Returns:
         Stripped standard output of the command.
     """
-    r = subprocess.run(cmd, shell=True, capture_output=True, text=True)
+    import shlex
+    # Strip shell redirects (2>/dev/null) — subprocess captures stderr anyway
+    clean = re.sub(r'\s*2>/dev/null\s*', '', cmd)
+    r = subprocess.run(shlex.split(clean), capture_output=True, text=True)
     return r.stdout.strip()
 
 

package/app/skills/rag-patterns/SKILL.md

@@ -3,6 +3,7 @@ name: rag-patterns
 description: "Loaded when user asks about RAG systems, embeddings, or vector search"
 effort: medium
 user-invocable: false
+allowed-tools: Read
 ---
 
 # RAG Patterns Skill

package/app/skills/research-mastery/SKILL.md

@@ -3,6 +3,7 @@ name: research-mastery
 description: "Loaded when user asks to research, verify, or synthesize information"
 effort: medium
 user-invocable: false
+allowed-tools: Read
 ---
 
 # Research Mastery Skill

package/app/skills/ruby-patterns/SKILL.md

@@ -3,6 +3,7 @@ name: ruby-patterns
 description: "Loaded when user asks about Ruby development patterns"
 effort: medium
 user-invocable: false
+allowed-tools: Read
 ---
 
 # Ruby Patterns

package/app/skills/rust-patterns/SKILL.md

@@ -3,6 +3,7 @@ name: rust-patterns
 description: "Loaded when user asks about Rust development patterns"
 effort: medium
 user-invocable: false
+allowed-tools: Read
 ---
 
 # Rust Patterns

package/app/skills/security-patterns/SKILL.md

@@ -3,6 +3,7 @@ name: security-patterns
 description: "Loaded when user asks about security, OWASP, or auth patterns"
 effort: medium
 user-invocable: false
+allowed-tools: Read
 ---
 
 # Security Patterns Skill

package/app/skills/skill-audit/SKILL.md

@@ -0,0 +1,137 @@
+---
+name: skill-audit
+description: "Scan skills and agents for security risks: dangerous patterns, secrets, excessive permissions"
+effort: medium
+disable-model-invocation: true
+argument-hint: "[skill-name | --all | --fix]"
+allowed-tools: Read, Grep, Glob, Bash
+---
+
+# /skill-audit - Skill Security Scanner
+
+$ARGUMENTS
+
+Scan skill and agent definitions for security risks before installation or after changes.
+
+## Usage
+
+```
+/skill-audit                  # Audit all skills
+/skill-audit debug            # Audit specific skill
+/skill-audit --all --fix      # Audit all + auto-fix safe issues
+```
+
+## What This Command Does
+
+1. **Scan SKILL.md frontmatter** for permission issues
+2. **Scan scripts/** for dangerous code patterns
+3. **Scan reference/** for hardcoded secrets
+4. **Report** findings with severity levels
+5. **Auto-fix** safe issues when `--fix` is passed
+
+## Security Checks
+
+### Frontmatter Checks
+
+| Check | Severity | Description |
+|-------|----------|-------------|
+| Overly permissive tools | WARN | `allowed-tools` includes Bash + Write + Edit without justification |
+| Missing allowed-tools | WARN | No tool restriction = full access |
+| Knowledge skill with Bash | HIGH | `user-invocable: false` skills should not need Bash |
+| Missing effort field | INFO | Best practice to declare effort |
+
+### Script Checks (Python)
+
+| Pattern | Severity | Description |
+|---------|----------|-------------|
+| `eval(` / `exec(` | HIGH | Arbitrary code execution |
+| `os.system(` | HIGH | Shell injection risk |
+| `subprocess.*shell=True` | HIGH | Shell injection risk |
+| `__import__` | WARN | Dynamic imports |
+| `pickle.loads` | HIGH | Deserialization attack |
+| `open(.*'w')` without path validation | WARN | Arbitrary file write |
+
+### Script Checks (Bash)
+
+| Pattern | Severity | Description |
+|---------|----------|-------------|
+| `curl.*\| bash` | HIGH | Remote code execution |
+| `curl.*\| sh` | HIGH | Remote code execution |
+| `wget.*\| bash` | HIGH | Remote code execution |
+| `rm -rf /` or `rm -rf ~` | HIGH | Destructive command |
+| Unquoted `$variables` in commands | WARN | Word splitting / injection |
+| `chmod 777` | WARN | Overly permissive |
+
+### Secret Detection
+
+| Pattern | Severity | Description |
+|---------|----------|-------------|
+| `AKIA[0-9A-Z]{16}` | HIGH | AWS access key |
+| `sk-[a-zA-Z0-9]{20,}` | HIGH | API key pattern |
+| `password\s*=\s*['"][^'"]+` | WARN | Hardcoded password |
+| `token\s*=\s*['"][^'"]+` | WARN | Hardcoded token |
+| `-----BEGIN.*PRIVATE KEY` | HIGH | Private key |
+| `ghp_[a-zA-Z0-9]{36}` | HIGH | GitHub PAT |
+
+## Output Format
+
+```markdown
+## Skill Audit Report
+
+### Summary
+- Skills scanned: N
+- HIGH: N | WARN: N | INFO: N
+
+### Findings
+
+#### [HIGH] skill-name/scripts/helper.py:12
+Pattern: `eval(user_input)`
+Risk: Arbitrary code execution
+Fix: Replace with `ast.literal_eval()` or explicit parsing
+
+#### [WARN] skill-name/SKILL.md (frontmatter)
+Pattern: Missing `allowed-tools`
+Risk: Skill has unrestricted tool access
+Fix: Add `allowed-tools: Read, Grep, Glob` (principle of least privilege)
+```
+
+## Steps
+
+1. Determine scope: single skill (`$ARGUMENTS`) or all skills
+2. For each skill directory in `app/skills/`:
+   a. Read `SKILL.md` — check frontmatter fields
+   b. Glob `scripts/**/*.py` — scan for dangerous Python patterns
+   c. Glob `scripts/**/*.sh` — scan for dangerous Bash patterns
+   d. Grep all files for secret patterns
+3. Also scan `app/agents/*.md` for overly broad tool lists
+4. Collect findings, sort by severity (HIGH > WARN > INFO)
+5. If `--fix` is passed:
+   - Add missing `allowed-tools` to SKILL.md frontmatter (suggest minimal set)
+   - Replace `eval(` with `ast.literal_eval(` where safe
+   - Do NOT auto-fix HIGH severity — only report
+6. Print audit report
+
+## Deterministic Scanner
+
+For CI pipelines or non-interactive use, run the Python scanner directly:
+
+```bash
+# Human-readable output
+python3 scripts/audit_skills.py
+
+# JSON output (for CI parsing)
+python3 scripts/audit_skills.py --json
+
+# CI mode: exit 1 on any HIGH finding
+python3 scripts/audit_skills.py --ci
+```
+
+The `/skill-audit` slash command wraps this scanner with Claude's analysis for remediation suggestions.
+
+## Rules
+
+- Never modify files without `--fix` flag
+- HIGH severity findings should block deployment
+- This skill is READ-ONLY by default
+- Scan both `app/skills/` and `app/agents/` directories
+- Exit with non-zero status if any HIGH findings exist (for CI integration)

package/app/skills/subagent-development/SKILL.md

@@ -4,7 +4,7 @@ description: "Execute implementation plans using fresh subagents per task with t
 user-invocable: true
 effort: high
 argument-hint: "[plan file or task description]"
-allowed-tools: Read, Write, Edit, Grep, Glob, Bash, Agent
+allowed-tools: Read, Write, Edit, Grep, Glob, Bash, Agent, TaskCreate, TaskList, TaskUpdate, TaskGet
 ---
 
 # Subagent Development

package/app/skills/swarm/SKILL.md

@@ -7,7 +7,7 @@ argument-hint: "[map-reduce|consensus|relay] [task]"
 context: fork
 agent: orchestrator
 model: opus
-allowed-tools: Bash, Read, Write, Edit, Glob, Grep, Agent, TeamCreate, TeamDelete, SendMessage, TaskCreate, TaskList, TaskUpdate
+allowed-tools: Bash, Read, Write, Edit, Glob, Grep, Agent, TeamCreate, TeamDelete, SendMessage, TaskCreate, TaskList, TaskUpdate, TaskGet, TaskOutput, TaskStop
 ---
 
 # /swarm - Parallel Agent Swarm

package/app/skills/swift-patterns/SKILL.md

@@ -3,6 +3,7 @@ name: swift-patterns
 description: "Loaded when user asks about Swift or iOS development patterns"
 effort: medium
 user-invocable: false
+allowed-tools: Read
 ---
 
 # Swift / iOS Patterns
@@ -487,7 +488,6 @@ Schemes: separate Debug/Release/Testing. Enable ASan + TSan in test schemes.
 ---
 
 ## Anti-Patterns
-
 | Anti-Pattern | Problem | Fix |
 |---|---|---|
 | Force unwrap `!` | Runtime crash | `guard let`, `if let`, `??` |

package/app/skills/teams/SKILL.md

@@ -4,7 +4,7 @@ description: "Launch pre-configured Agent Teams for common workflows"
 effort: max
 user-invocable: true
 argument-hint: "<preset> [task-description]"
-allowed-tools: Bash, Read, Write, Edit, Glob, Grep
+allowed-tools: Bash, Read, Write, Edit, Glob, Grep, Agent, TeamCreate, TeamDelete, SendMessage, TaskCreate, TaskList, TaskUpdate, TaskGet
 ---
 
 # /teams - Agent Teams Presets

package/app/skills/testing-patterns/SKILL.md

@@ -3,6 +3,7 @@ name: testing-patterns
 description: "Loaded when user asks about testing strategy, fixtures, or mocking"
 effort: medium
 user-invocable: false
+allowed-tools: Read
 ---
 
 # Testing Patterns Skill

package/app/skills/typescript-patterns/SKILL.md

@@ -3,6 +3,7 @@ name: typescript-patterns
 description: "Loaded when user asks about TypeScript patterns or type safety"
 effort: medium
 user-invocable: false
+allowed-tools: Read
 ---
 
 # TypeScript/JavaScript Patterns

package/app/skills/verification-before-completion/SKILL.md

@@ -2,6 +2,7 @@
 name: verification-before-completion
 description: "Loaded when agent is about to claim work is complete, fixed, or passing — requires running verification commands and confirming output before making any success claims. Evidence before assertions, always."
 user-invocable: false
+allowed-tools: Read
 ---
 
 # Verification Before Completion

package/app/skills/workflow/SKILL.md

@@ -7,7 +7,7 @@ argument-hint: "[type] [task description]"
 context: fork
 agent: orchestrator
 model: opus
-allowed-tools: Bash, Read, Write, Edit, Glob, Grep, Agent, TeamCreate, TeamDelete, SendMessage, TaskCreate, TaskList, TaskUpdate
+allowed-tools: Bash, Read, Write, Edit, Glob, Grep, Agent, TeamCreate, TeamDelete, SendMessage, TaskCreate, TaskList, TaskUpdate, TaskGet, TaskOutput, TaskStop
 ---
 
 # /workflow - Autonomous Agent Workflow

package/kb/reference/architecture-overview.md

@@ -13,7 +13,7 @@ description: "Architecture of ai-toolkit: directory layout, global install model
 
 ## Purpose
 
-Shared, project-agnostic AI development toolkit for Claude Code (and compatible assistants like Cursor, Windsurf, Copilot, Gemini, Cline, Roo Code, and Aider). Provides 47 specialized agents, 85 skills (slash commands + knowledge), expanded lifecycle hooks, and experimental opt-in plugin packs that teams can adopt separately from the default global install.
+Shared, project-agnostic AI development toolkit for Claude Code (and compatible assistants like Cursor, Windsurf, Copilot, Gemini, Cline, Roo Code, Aider, and Augment). Provides 47 specialized agents, 87 skills (slash commands + knowledge), expanded lifecycle hooks, persona presets, and experimental opt-in plugin packs that teams can adopt separately from the default global install.
 
 ## Design Principles
 
@@ -31,7 +31,7 @@ ai-toolkit/
     ai-toolkit.js        # CLI entry point (install, init, add-rule, ...)
   app/                       # All toolkit components
     agents/                  # 47 agent definitions (.md + YAML frontmatter)
-    skills/                  # 85 skills: task, hybrid, knowledge
+    skills/                  # 87 skills: task, hybrid, knowledge
     rules/                   # Rules auto-injected into ~/.claude/CLAUDE.md
     hooks/                   # Hook scripts (copied to ~/.ai-toolkit/hooks/)
     hooks.json               # Hook definitions (merged into ~/.claude/settings.json)
@@ -165,8 +165,8 @@ Three tiers determine how to approach a task:
 
 | Type | Field | Invocation | Count |
 |------|-------|-----------|-------|
-| Task | `disable-model-invocation: true` | User via `/skill` only | 27 |
-| Hybrid | (neither) | User via `/skill` + agent knowledge | 27 |
+| Task | `disable-model-invocation: true` | User via `/skill` only | 28 |
+| Hybrid | (neither) | User via `/skill` + agent knowledge | 28 |
 | Knowledge | `user-invocable: false` | Claude auto-loads | 31 |
 
 ## Multi-Agent Execution
@@ -209,7 +209,7 @@ Agents (code-reviewer, debugger, devops-implementer, ...)
 | TeammateIdle | Agent Teams: idle | *(inline)* | Completeness reminder |
 | SubagentStart | Subagent spawn | `subagent-start.sh` | Scope reminder for subagents |
 | SubagentStop | Subagent completion | `subagent-stop.sh` | Handoff checklist for subagents |
-| PreCompact | Before compaction | `pre-compact.sh` | Save context before compaction |
+| PreCompact | Before compaction | `pre-compact.sh` | Save prioritized context: instincts > tasks > git state > decisions |
 | SessionEnd | Session end | `session-end.sh` | Persist handoff note for the next session |
 
 Scripts at `~/.ai-toolkit/hooks/`. See [hooks-catalog.md](hooks-catalog.md) for details.
@@ -224,6 +224,29 @@ Scripts at `~/.ai-toolkit/hooks/`. See [hooks-catalog.md](hooks-catalog.md) for
 | IV Self-Preservation | Constitution is read-only, kill switch via system-governor |
 | V Resource Governance | No destructive commands without confirmation |
 
+## Persona Presets
+
+Optional engineering personas injected via `ai-toolkit install --persona <name>`. Each persona adds role-specific communication style, preferred skills, and code review priorities to CLAUDE.md.
+
+| Persona | Focus |
+|---------|-------|
+| `backend-lead` | System design, scalability, data integrity, API stability |
+| `frontend-lead` | Component architecture, a11y, state management, Core Web Vitals |
+| `devops-eng` | Infrastructure as code, CI/CD, rollback safety, observability |
+| `junior-dev` | Step-by-step explanations, learning resources, small PRs |
+
+Persona files live in `app/personas/*.md` and use the same `inject_rule` mechanism as registered rules.
+
+## Skill Security Auditing
+
+`/skill-audit` scans `app/skills/` and `app/agents/` for security risks:
+- **Frontmatter**: overly permissive `allowed-tools`, knowledge skills with Bash
+- **Scripts**: `eval()`, `exec()`, `os.system()`, `subprocess(shell=True)`, `pickle.loads`
+- **Secrets**: AWS keys, GitHub PATs, private keys, hardcoded passwords
+- **Bash**: `curl | bash`, unquoted variables, `chmod 777`
+
+Severity levels: HIGH (blocks deployment), WARN (should fix), INFO (best practice). CI-ready with non-zero exit on HIGH findings.
+
 ## Agent Model Tiers
 
 | Model | Purpose | Count |

package/kb/reference/hooks-catalog.md

@@ -199,10 +199,12 @@ Skipped when `TOOLKIT_HOOK_PROFILE=minimal`.
 | Script | `~/.ai-toolkit/hooks/pre-compact.sh` |
 | Fires | Before context compaction |
 
-**Actions:**
-1. Injects reminder to re-read CLAUDE.md files after compaction
-2. Preserves session context from `.claude/session-context.md` (if exists)
-3. Preserves active instincts from `.claude/instincts/*.md` (if any)
+**Actions (prioritized — higher priority items survive tighter token budgets):**
+1. **Mandatory reload reminder** — always emitted, instructs Claude to re-read CLAUDE.md and active tasks
+2. **Active instincts** — lists each instinct with confidence score and pattern name from `.claude/instincts/*.md`
+3. **Session context** — preserves task state from `.claude/session-context.md` (if exists)
+4. **Git working state** — branch name, uncommitted change count, last commit (if inside a git repo)
+5. **Key decisions** — last 10 lines from `.claude/decisions.md` (if exists)
 
 Skipped when `TOOLKIT_HOOK_PROFILE=minimal`.
 

package/kb/reference/skills-catalog.md

@@ -9,7 +9,7 @@ last_updated: "2026-04-01"
 description: "Complete catalog of 85 skills: 27 task, 27 hybrid, 31 knowledge. Includes effort levels, skill-scoped hooks, executable scripts, and creator workflows."
 ---
 
-# Skills Catalog (85 skills)
+# Skills Catalog (87 skills)
 
 All functionality is unified under skills. Task and hybrid skills are user-invocable as slash commands. Knowledge skills provide domain patterns auto-loaded by agents.
 
@@ -21,7 +21,7 @@ All functionality is unified under skills. Task and hybrid skills are user-invoc
 | **2 — Multi-agent workflow** | `/workflow <type>` | Cross-cutting task with known pattern |
 | **3 — Custom parallelism** | `/orchestrate`, `/swarm` | No predefined workflow matches |
 
-## Task Skills (27)
+## Task Skills (28)
 
 Task skills execute a specific action. Invoked via slash commands. `disable-model-invocation: true`.
 
@@ -54,8 +54,9 @@ Task skills execute a specific action. Invoked via slash commands. `disable-mode
 | **plugin-creator** | `/plugin-creator` | high | Create experimental opt-in plugin packs with manifests, conventions, and optional modules |
 | **health** | `/health` | medium | Check health of project services (auto-detect) |
 | **prd-to-issues** | `/prd-to-issues` | medium | Break PRD into GitHub issues with vertical slices and HITL/AFK tagging |
+| **skill-audit** | `/skill-audit` | medium | Scan skills and agents for security risks: dangerous patterns, secrets, excessive permissions |
 
-## Hybrid Skills (27)
+## Hybrid Skills (28)
 
 Hybrid skills combine slash-command invocation with domain knowledge that agents reference.
 
@@ -88,6 +89,7 @@ Hybrid skills combine slash-command invocation with domain knowledge that agents
 | **subagent-development** | `/subagent-development` | high | Execute plans with 2-stage review (spec + quality) per task |
 | **repeat** | `/repeat` | medium | Autonomous loop with safety controls (Ralph Wiggum pattern) |
 | **mem-search** | `/mem-search` | medium | Search past coding sessions via natural language (memory-pack) |
+| **persona** | `/persona` | low | Switch engineering persona at runtime (backend-lead, frontend-lead, devops-eng, junior-dev) |
 
 ### `/workflow` types
 

package/llms.txt

@@ -1,6 +1,6 @@
 # ai-toolkit
 
-> Professional-grade Claude Code toolkit: 85 skills, 47 agents, machine-enforced constitution, quality hooks.
+> Professional-grade Claude Code toolkit: 87 skills, 47 agents, machine-enforced constitution, quality hooks.
 
 ## Documentation
 
@@ -32,7 +32,7 @@
 - [Plugin Pack Conventions](kb/reference/plugin-pack-conventions.md)
 - [Quick Wins Implementation Summary](kb/reference/quick-wins-implementation-summary.md)
 - [Skill Templates](kb/reference/skill-templates.md)
-- [Skills Catalog (85 skills)](kb/reference/skills-catalog.md)
+- [Skills Catalog (87 skills)](kb/reference/skills-catalog.md)
 - [Skills Unification Model](kb/reference/skills-unification.md)
 - [Usage Statistics](kb/reference/stats.md)
 - [Config Sync](kb/reference/sync.md)

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@softspark/ai-toolkit",
-  "version": "1.0.0",
-  "description": "Professional-grade AI coding toolkit: 85 skills, 47 agents, multi-platform support (Claude, Cursor, Windsurf, Copilot, Gemini, Cline, Roo Code, Aider), machine-enforced safety constitution, Iron Law enforcement, persistent memory, visual brainstorming, expanded lifecycle hooks, 11 plugin packs, and benchmark tooling.",
+  "version": "1.2.0",
+  "description": "Professional-grade AI coding toolkit: 87 skills, 47 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",
     "claude-code",
@@ -20,6 +20,7 @@
     "roo-code",
     "roo",
     "aider",
+    "augment",
     "multi-platform"
   ],
   "homepage": "https://github.com/softspark/ai-toolkit",