@softspark/ai-toolkit 1.0.0

package/app/skills/command-creator/SKILL.md

@@ -0,0 +1,83 @@
+---
+name: command-creator
+description: "Creates new Claude Code slash commands with frontmatter, workflow guidance, and validation"
+effort: high
+disable-model-invocation: true
+argument-hint: "[command name or description]"
+allowed-tools: Read, Write, Edit, Bash, Grep, Glob
+---
+
+# Command Creator
+
+$ARGUMENTS
+
+Create a new Claude Code slash command following ai-toolkit conventions.
+
+## Workflow
+
+1. **Capture intent** -- what should the command do and who invokes it?
+2. **Pick scope** -- project command, user command, or plugin command?
+3. **Define frontmatter** -- description, argument hint, allowed tools, model if needed
+4. **Write command body** -- instructions for Claude, not explanation for the user
+5. **Add validation context** -- expected output, constraints, follow-up checks
+6. **Test and iterate** -- invoke the command with representative arguments
+
+## Command Locations
+
+- Project: `.claude/commands/<name>.md`
+- User: `~/.claude/commands/<name>.md`
+- Plugin: `plugin-name/commands/<name>.md`
+
+In `ai-toolkit`, command-development guidance belongs in skill form and any reusable command templates should live under `app/skills/<skill-name>/templates/` or KB docs.
+
+## Frontmatter Template
+
+```yaml
+---
+description: "One-line help text shown in /help"
+argument-hint: "[target]"
+allowed-tools: Read, Grep, Bash
+model: sonnet
+---
+```
+
+## Command Authoring Rules
+
+- Write commands as **instructions for Claude**, not marketing copy for the user
+- Keep the first paragraph action-oriented and deterministic
+- Use `$ARGUMENTS` early when the command takes user input
+- Prefer numbered phases for multi-step workflows
+- List required checks explicitly (`lint`, `tests`, `docs`, etc.)
+- Avoid hidden assumptions about project structure unless the command is project-specific
+
+## Minimal Template
+
+```markdown
+---
+description: "{one-line description}"
+argument-hint: "[arguments]"
+allowed-tools: Read, Grep, Bash
+---
+
+# {Command Title}
+
+$ARGUMENTS
+
+Perform the requested task using this workflow:
+
+1. Gather context from the repository.
+2. Ask clarifying questions if critical information is missing.
+3. Execute the task using the smallest safe set of changes.
+4. Validate the result.
+5. Summarize outcome and follow-up actions.
+```
+
+## Validation Checklist
+
+- [ ] Command file uses markdown and valid YAML frontmatter
+- [ ] Help text is concise and searchable
+- [ ] Body is instruction-oriented, not user-facing prose
+- [ ] `$ARGUMENTS` is present when arguments are expected
+- [ ] Validation steps are explicit
+- [ ] Command has been tested with at least one realistic invocation
+

package/app/skills/commit/SKILL.md

@@ -0,0 +1,98 @@
+---
+name: commit
+description: "Create Conventional Commits with pre-commit validation"
+effort: medium
+disable-model-invocation: true
+argument-hint: "[message or scope]"
+allowed-tools: Bash, Read, Grep
+hooks:
+  PreToolUse:
+    - matcher: "Bash"
+      hooks:
+        - type: command
+          command: "echo 'Reminder: ensure linting passes before committing'"
+---
+
+# Git Commit
+
+$ARGUMENTS
+
+Creates well-structured git commits following Conventional Commits specification.
+
+## Project context
+
+- Staged changes: !`git diff --cached --stat 2>/dev/null || echo "nothing staged"`
+- Current branch: !`git branch --show-current 2>/dev/null`
+
+## Commit Format
+
+```
+<type>(<scope>): <description>
+
+[optional body]
+
+[optional footer]
+```
+
+## Types
+
+| Type | Description |
+|------|-------------|
+| `feat` | New feature |
+| `fix` | Bug fix |
+| `docs` | Documentation only |
+| `style` | Formatting, no code change |
+| `refactor` | Code restructuring |
+| `perf` | Performance improvement |
+| `test` | Adding/updating tests |
+| `chore` | Maintenance tasks |
+| `ci` | CI/CD changes |
+
+## Examples
+
+```bash
+# Feature
+git commit -m "$(cat <<'EOF'
+feat(search): add multi-hop reasoning support
+
+- Implement query decomposition
+- Add iterative retrieval with reasoning
+- Include answer synthesis from aggregated context
+EOF
+)"
+
+# Bug fix
+git commit -m "$(cat <<'EOF'
+fix(cache): resolve connection pool exhaustion
+
+Root cause: connections not returned to pool on error
+Solution: use context manager for automatic cleanup
+
+Fixes #123
+EOF
+)"
+```
+
+## Automated Pre-Commit Check
+
+Run the bundled script for structured pre-commit analysis:
+
+```bash
+python3 ${CLAUDE_SKILL_DIR}/scripts/pre-commit-check.py
+```
+
+Use the output to validate staged changes, detect secrets, and suggest commit type/scope.
+
+## Pre-Commit Checklist
+
+Before committing:
+- [ ] Run linting: `make lint` (or `docker exec {app-container} make lint`)
+- [ ] Run tests: `make test` (or `docker exec {app-container} make test`)
+- [ ] Check for secrets: No API keys or passwords
+
+## Git Safety
+
+- NEVER use `--force` push without explicit request
+- NEVER skip hooks (`--no-verify`) unless explicitly asked
+- ALWAYS create NEW commits (don't amend previous unless asked)
+- Stage specific files, avoid `git add -A` with sensitive files

package/app/skills/commit/scripts/pre-commit-check.py

@@ -0,0 +1,87 @@
+#!/usr/bin/env python3
+"""Pre-commit validation: staged files, secrets detection, commit type suggestion."""
+import json, subprocess, re, sys
+
+def run(cmd):
+    r = subprocess.run(cmd, capture_output=True, text=True)
+    return r.stdout.strip()
+
+def main():
+    branch = run(["git", "branch", "--show-current"])
+    staged_raw = run(["git", "diff", "--cached", "--name-only"])
+    staged = staged_raw.split('\n') if staged_raw else []
+    stat = run(["git", "diff", "--cached", "--stat"])
+
+    # Detect secrets patterns
+    diff = run(["git", "diff", "--cached"])
+    secret_patterns = [
+        r'(?i)(api[_-]?key|secret|password|token|bearer)\s*[=:]\s*["\'][^"\']{8,}',
+        r'(?i)AKIA[0-9A-Z]{16}',  # AWS
+        r'sk-[a-zA-Z0-9]{20,}',   # OpenAI
+    ]
+    secrets = []
+    for i, line in enumerate(diff.split('\n')):
+        if line.startswith('+') and not line.startswith('+++'):
+            for p in secret_patterns:
+                if re.search(p, line):
+                    secrets.append({"line": i, "pattern": p.split(')')[0].split('(')[-1], "preview": line[:80]})
+
+    # Large files (>1MB)
+    large = []
+    for f in staged:
+        try:
+            r = subprocess.run(
+                ["git", "cat-file", "-s", f":{f}"],
+                stdout=subprocess.PIPE, stderr=subprocess.DEVNULL, text=True,
+            )
+            size = int(r.stdout.strip() or "0")
+            if size > 1_000_000:
+                large.append({"file": f, "size_mb": round(size/1_000_000, 1)})
+        except (ValueError, subprocess.SubprocessError):
+            pass
+
+    # Suggest type from file paths
+    type_map = {"test": "test", "doc": "docs", "README": "docs", ".yml": "ci", ".yaml": "ci",
+                "Dockerfile": "ci", "migration": "feat", "fix": "fix"}
+    type_suggestion = "feat"
+    for f in staged:
+        for key, val in type_map.items():
+            if key.lower() in f.lower():
+                type_suggestion = val
+                break
+
+    # Suggest scope from common directory
+    scopes = set()
+    for f in staged:
+        parts = f.split('/')
+        if len(parts) > 1:
+            scopes.add(parts[0] if parts[0] != 'src' and parts[0] != 'app' else (parts[1] if len(parts) > 2 else parts[0]))
+    scope_suggestion = list(scopes)[0] if len(scopes) == 1 else None
+
+    # Parse additions/deletions
+    additions = len([l for l in diff.split('\n') if l.startswith('+') and not l.startswith('+++')])
+    deletions = len([l for l in diff.split('\n') if l.startswith('-') and not l.startswith('---')])
+
+    result = {
+        "branch": branch,
+        "staged_files": len(staged),
+        "staged_file_list": staged[:20],
+        "additions": additions,
+        "deletions": deletions,
+        "type_suggestion": type_suggestion,
+        "scope_suggestion": scope_suggestion,
+        "secrets_detected": secrets,
+        "large_files": large,
+        "warnings": []
+    }
+    if secrets:
+        result["warnings"].append(f"SECRETS DETECTED: {len(secrets)} potential secrets in staged changes")
+    if large:
+        result["warnings"].append(f"LARGE FILES: {len(large)} files over 1MB")
+    if not staged:
+        result["warnings"].append("NO FILES STAGED: nothing to commit")
+
+    print(json.dumps(result, indent=2))
+
+if __name__ == "__main__":
+    main()

package/app/skills/commit/templates/conventional-commit.md

@@ -0,0 +1,52 @@
+# Conventional Commit Template
+
+```
+<type>(<scope>): <description>
+
+<body>
+
+<footer>
+
+Co-Authored-By: Claude <noreply@anthropic.com>
+```
+
+## Types
+
+| Type | When to use |
+|------|-------------|
+| `feat` | New feature for the user |
+| `fix` | Bug fix for the user |
+| `docs` | Documentation only changes |
+| `style` | Formatting, missing semicolons, etc. |
+| `refactor` | Code change that neither fixes a bug nor adds a feature |
+| `perf` | Performance improvement |
+| `test` | Adding or correcting tests |
+| `chore` | Build process, auxiliary tools, libraries |
+| `ci` | CI/CD configuration changes |
+| `revert` | Reverts a previous commit |
+
+## Scope examples
+
+- `auth`, `api`, `db`, `ui`, `config`, `deps`, `docker`, `ci`
+
+## Breaking changes
+
+Add `!` after type/scope and `BREAKING CHANGE:` in footer:
+```
+feat(api)!: change authentication endpoint
+
+BREAKING CHANGE: /auth/login now requires email instead of username
+```
+
+## Multi-line body
+
+Use bullet points for multiple changes:
+```
+feat(search): add advanced filtering
+
+- Add date range filter
+- Add category filter with multi-select
+- Add saved filters functionality
+
+Closes #456
+```