@softspark/ai-toolkit 1.3.14 → 1.4.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +41 -0
- package/README.md +62 -16
- package/app/agents/backend-specialist.md +8 -0
- package/app/agents/code-reviewer.md +9 -0
- package/app/agents/database-architect.md +8 -0
- package/app/agents/debugger.md +8 -0
- package/app/agents/devops-implementer.md +8 -0
- package/app/agents/documenter.md +8 -0
- package/app/agents/frontend-specialist.md +8 -0
- package/app/agents/performance-optimizer.md +8 -0
- package/app/agents/security-auditor.md +9 -0
- package/app/agents/test-engineer.md +9 -0
- package/app/skills/analyze/SKILL.md +15 -0
- package/app/skills/api-patterns/SKILL.md +10 -0
- package/app/skills/ci-cd-patterns/SKILL.md +10 -0
- package/app/skills/clean-code/SKILL.md +10 -0
- package/app/skills/database-patterns/SKILL.md +10 -0
- package/app/skills/debug/SKILL.md +16 -0
- package/app/skills/docs/SKILL.md +16 -0
- package/app/skills/git-mastery/SKILL.md +10 -0
- package/app/skills/onboard/SKILL.md +15 -0
- package/app/skills/performance-profiling/SKILL.md +10 -0
- package/app/skills/plan/SKILL.md +16 -0
- package/app/skills/refactor/SKILL.md +16 -0
- package/app/skills/review/SKILL.md +58 -3
- package/app/skills/security-patterns/SKILL.md +10 -0
- package/app/skills/tdd/SKILL.md +6 -0
- package/app/skills/testing-patterns/SKILL.md +10 -0
- package/bin/ai-toolkit.js +33 -5
- package/kb/procedures/release-verification-sop.md +283 -0
- package/kb/reference/architecture-overview.md +36 -7
- package/kb/reference/competitive-features-implementation.md +51 -52
- package/kb/reference/language-rules.md +18 -4
- package/kb/reference/skills-catalog.md +57 -1
- package/llms-full.txt +451 -64
- package/llms.txt +1 -0
- package/manifest.json +1 -1
- package/package.json +4 -2
- package/scripts/dir_rules_shared.py +441 -0
- package/scripts/generate_antigravity.py +36 -0
- package/scripts/generate_augment_rules.py +107 -0
- package/scripts/generate_cline_rules.py +31 -0
- package/scripts/generate_conventions.py +37 -0
- package/scripts/generate_cursor_mdc.py +127 -0
- package/scripts/generate_roo_rules.py +30 -0
- package/scripts/generate_windsurf_rules.py +31 -0
- package/scripts/install.py +26 -1
- package/scripts/install_steps/ai_tools.py +149 -31
- package/scripts/install_steps/detect_language.py +68 -5
|
@@ -117,17 +117,40 @@ After all reviewers complete:
|
|
|
117
117
|
- **Lines Added**: [+count]
|
|
118
118
|
- **Lines Removed**: [-count]
|
|
119
119
|
- **Issues Found**: [count]
|
|
120
|
+
- **Overall Confidence**: [1-10] — how confident the reviewer is in the assessment
|
|
120
121
|
|
|
121
122
|
### Findings
|
|
122
123
|
|
|
123
124
|
#### Critical
|
|
124
125
|
- **[file:line]**: [issue]
|
|
125
|
-
- [
|
|
126
|
+
- Severity: critical | Confidence: [1-10]
|
|
127
|
+
- Evidence: [specific code reference and reasoning]
|
|
126
128
|
- Suggested fix: [code]
|
|
127
129
|
|
|
128
|
-
####
|
|
130
|
+
#### Major
|
|
131
|
+
- **[file:line]**: [issue]
|
|
132
|
+
- Severity: major | Confidence: [1-10]
|
|
133
|
+
- Evidence: [specific code reference and reasoning]
|
|
134
|
+
- Suggested fix: [code]
|
|
135
|
+
|
|
136
|
+
#### Minor
|
|
137
|
+
- **[file:line]**: [issue]
|
|
138
|
+
- Severity: minor | Confidence: [1-10]
|
|
139
|
+
- Evidence: [line number + reasoning]
|
|
140
|
+
|
|
141
|
+
#### Nit
|
|
129
142
|
- **[file:line]**: [suggestion]
|
|
130
|
-
- [
|
|
143
|
+
- Severity: nit | Confidence: [1-10]
|
|
144
|
+
|
|
145
|
+
### Confidence Guide
|
|
146
|
+
|
|
147
|
+
| Score | Meaning |
|
|
148
|
+
|-------|---------|
|
|
149
|
+
| 9-10 | Certain — verified via code, tests, or documentation |
|
|
150
|
+
| 7-8 | High — strong evidence, minor assumptions |
|
|
151
|
+
| 5-6 | Medium — plausible issue, needs author confirmation |
|
|
152
|
+
| 3-4 | Low — speculative, based on patterns not proof |
|
|
153
|
+
| 1-2 | Guess — flag for discussion, don't block on this |
|
|
131
154
|
|
|
132
155
|
### Positive Notes
|
|
133
156
|
- [What's good about the code]
|
|
@@ -136,6 +159,38 @@ After all reviewers complete:
|
|
|
136
159
|
[APPROVE / REQUEST_CHANGES / NEEDS_DISCUSSION]
|
|
137
160
|
```
|
|
138
161
|
|
|
162
|
+
## Common Rationalizations
|
|
163
|
+
|
|
164
|
+
| Excuse | Why It's Wrong |
|
|
165
|
+
|--------|----------------|
|
|
166
|
+
| "Small change, quick scan is enough" | Small changes introduce subtle bugs — apply consistent review regardless of size |
|
|
167
|
+
| "Tests pass, so the code is correct" | Tests validate specific scenarios, not all behaviors — verify missing coverage |
|
|
168
|
+
| "It's just a refactor, no need for deep review" | Refactors change invariants — verify behavior preservation, not just compilation |
|
|
169
|
+
| "The author is senior, they know what they're doing" | Seniority doesn't prevent mistakes — review the code, not the person |
|
|
170
|
+
| "We're in a hurry, ship it" | Rushed reviews create tech debt that costs 10x more to fix later |
|
|
171
|
+
|
|
172
|
+
## Self-Evaluation (LLM-as-Judge)
|
|
173
|
+
|
|
174
|
+
After completing the review, perform a self-evaluation pass:
|
|
175
|
+
|
|
176
|
+
### Check for Blind Spots
|
|
177
|
+
1. **Did I verify, or assume?** — For each finding, confirm you read the actual code (not inferred from context)
|
|
178
|
+
2. **Did I miss the inverse?** — If you flagged X as a problem, did you check if NOT doing X is also a problem elsewhere?
|
|
179
|
+
3. **Did I anchor on the first issue?** — Review whether early findings biased you toward similar patterns, missing different issue classes
|
|
180
|
+
4. **Did I check the unhappy path?** — Error handling, edge cases, failure modes — not just the golden path
|
|
181
|
+
5. **Did I flag uncertainty?** — Findings with confidence < 6 should be clearly marked as "needs author input"
|
|
182
|
+
|
|
183
|
+
### Calibrate Confidence
|
|
184
|
+
- If all findings are confidence 7+, you may be overconfident — re-examine the weakest finding
|
|
185
|
+
- If any finding lacks a file:line reference, downgrade it or remove it
|
|
186
|
+
- If you found zero issues, state what you specifically checked (not "looks good")
|
|
187
|
+
|
|
139
188
|
## READ-ONLY
|
|
140
189
|
|
|
141
190
|
This skill only analyzes. It does NOT modify any files.
|
|
191
|
+
|
|
192
|
+
## Related Skills
|
|
193
|
+
- Issues found? → `/debug` to trace root causes
|
|
194
|
+
- Missing tests? → `/tdd` to add test-first coverage
|
|
195
|
+
- Security findings? → `/cve-scan` for dependency vulnerabilities
|
|
196
|
+
- Architecture concerns? → `/analyze` for deeper code quality metrics
|
|
@@ -81,6 +81,16 @@ async def resource():
|
|
|
81
81
|
|
|
82
82
|
---
|
|
83
83
|
|
|
84
|
+
## Common Rationalizations
|
|
85
|
+
|
|
86
|
+
| Excuse | Why It's Wrong |
|
|
87
|
+
|--------|----------------|
|
|
88
|
+
| "It's an internal API, security doesn't matter" | Internal APIs get exposed — lateral movement is attackers' primary technique |
|
|
89
|
+
| "The framework handles security" | Frameworks provide tools, not guarantees — misconfiguration is OWASP #5 |
|
|
90
|
+
| "We'll add auth later" | Unauthenticated endpoints in production get discovered within hours |
|
|
91
|
+
| "Nobody would exploit this" | Automated scanners don't care about your threat model — they scan everything |
|
|
92
|
+
| "It's behind a VPN" | VPNs are perimeter defense — zero trust assumes breach already happened |
|
|
93
|
+
|
|
84
94
|
## Reference Guides
|
|
85
95
|
|
|
86
96
|
For authentication patterns (JWT, passwords, token strategy), see [reference/authentication.md](reference/authentication.md).
|
package/app/skills/tdd/SKILL.md
CHANGED
|
@@ -172,3 +172,9 @@ Before marking work complete:
|
|
|
172
172
|
- [ ] Edge cases and errors covered
|
|
173
173
|
|
|
174
174
|
Can't check all boxes? You skipped TDD. Start over.
|
|
175
|
+
|
|
176
|
+
## Related Skills
|
|
177
|
+
- Feature complete? → `/review` to get a code review
|
|
178
|
+
- Need to plan the feature first? → `/plan` for task breakdown
|
|
179
|
+
- Want a full test coverage sweep? → `/workflow test-coverage`
|
|
180
|
+
- Debugging a test failure? → `/debug` for systematic root cause analysis
|
|
@@ -72,3 +72,13 @@ For PHP PHPUnit patterns, see [reference/php-phpunit.md](reference/php-phpunit.m
|
|
|
72
72
|
For Go testing patterns, see [reference/go-testing.md](reference/go-testing.md).
|
|
73
73
|
|
|
74
74
|
For Flutter/Dart testing patterns, see [reference/flutter-testing.md](reference/flutter-testing.md).
|
|
75
|
+
|
|
76
|
+
## Common Rationalizations
|
|
77
|
+
|
|
78
|
+
| Excuse | Why It's Wrong |
|
|
79
|
+
|--------|----------------|
|
|
80
|
+
| "It's too simple to test" | Simple code breaks in integration — test the contract, not the complexity |
|
|
81
|
+
| "Tests slow down development" | Tests slow down bugs reaching production — that's the point |
|
|
82
|
+
| "We'll add tests later" | Untested code accumulates — later means never, and coverage gaps compound |
|
|
83
|
+
| "Mocking everything is fine" | Over-mocking tests the mocks, not the code — mock at boundaries only |
|
|
84
|
+
| "100% coverage means no bugs" | Coverage measures execution, not correctness — focus on behavior assertions |
|
package/bin/ai-toolkit.js
CHANGED
|
@@ -76,17 +76,24 @@ const COMMANDS = {
|
|
|
76
76
|
mcp: 'Manage MCP server templates (list, show, add, remove)',
|
|
77
77
|
plugin: 'Manage plugin packs (install, remove, update, clean, list, status)',
|
|
78
78
|
sync: 'Sync config to/from GitHub Gist (--export, --push, --pull, --import)',
|
|
79
|
-
'cursor-rules': 'Generate .cursorrules for Cursor IDE',
|
|
80
|
-
'
|
|
79
|
+
'cursor-rules': 'Generate .cursorrules for Cursor IDE (legacy)',
|
|
80
|
+
'cursor-mdc': 'Generate .cursor/rules/*.mdc for Cursor IDE (recommended)',
|
|
81
|
+
'windsurf-rules': 'Generate .windsurfrules for Windsurf (legacy)',
|
|
82
|
+
'windsurf-dir-rules': 'Generate .windsurf/rules/*.md for Windsurf (recommended)',
|
|
81
83
|
'copilot-instructions': 'Generate .github/copilot-instructions.md',
|
|
82
84
|
'gemini-md': 'Generate GEMINI.md for Gemini CLI',
|
|
83
|
-
'cline-rules': 'Generate .clinerules for Cline',
|
|
85
|
+
'cline-rules': 'Generate .clinerules for Cline (legacy)',
|
|
86
|
+
'cline-dir-rules': 'Generate .cline/rules/*.md for Cline (recommended)',
|
|
84
87
|
'roo-modes': 'Generate .roomodes for Roo Code',
|
|
88
|
+
'roo-dir-rules': 'Generate .roo/rules/*.md shared rules for Roo Code',
|
|
85
89
|
'aider-conf': 'Generate .aider.conf.yml for Aider',
|
|
86
|
-
'
|
|
90
|
+
'conventions-md': 'Generate CONVENTIONS.md for Aider (auto-loaded)',
|
|
91
|
+
'augment-rules': 'Generate .augment/rules/ai-toolkit.md for Augment (legacy)',
|
|
92
|
+
'augment-dir-rules': 'Generate .augment/rules/ai-toolkit-*.md for Augment (recommended)',
|
|
93
|
+
'antigravity-rules': 'Generate .agent/rules/ and .agent/workflows/ for Google Antigravity',
|
|
87
94
|
'agents-md': 'Regenerate AGENTS.md from agent definitions',
|
|
88
95
|
'llms-txt': 'Generate llms.txt and llms-full.txt',
|
|
89
|
-
'generate-all': 'Generate all platform configs at once (agents, cursor, windsurf, copilot, gemini, cline, roo, aider, augment, llms)',
|
|
96
|
+
'generate-all': 'Generate all platform configs at once (agents, cursor, windsurf, copilot, gemini, cline, roo, aider, augment, antigravity, llms)',
|
|
90
97
|
help: 'Show this help message',
|
|
91
98
|
};
|
|
92
99
|
|
|
@@ -191,6 +198,9 @@ function showHelp() {
|
|
|
191
198
|
console.log(' --local Also set up project-local configs (CLAUDE.md, settings, constitution, copilot, cline, roo, aider, git hooks)');
|
|
192
199
|
console.log(' --profile <p> Install profile: minimal (agents+skills), standard (default), strict (all+git hooks)');
|
|
193
200
|
console.log(' --modules <list> Install specific modules (e.g. core,agents,rules-typescript)');
|
|
201
|
+
console.log(' --lang <list> Explicitly select language rules (e.g. typescript, go,python)');
|
|
202
|
+
console.log(' --editors <list> Install editor configs: cursor,windsurf,cline,roo,aider,augment,copilot,antigravity (or "all")');
|
|
203
|
+
console.log(' Default with --local: auto-detect from existing project files');
|
|
194
204
|
console.log(' --auto-detect Detect project languages and install matching rule modules');
|
|
195
205
|
console.log(' --list, --dry-run Dry-run: show what would be applied');
|
|
196
206
|
console.log('\nOptions for create:');
|
|
@@ -372,6 +382,17 @@ function handleGenerateAll(_args) {
|
|
|
372
382
|
for (const gen of Object.values(GENERATORS)) {
|
|
373
383
|
writeGeneratorOutput(gen);
|
|
374
384
|
}
|
|
385
|
+
// Directory-based generators (multi-file output)
|
|
386
|
+
run(scriptPath('generate_antigravity.py'), [CWD]);
|
|
387
|
+
run(scriptPath('generate_cursor_mdc.py'), [CWD]);
|
|
388
|
+
run(scriptPath('generate_windsurf_rules.py'), [CWD]);
|
|
389
|
+
run(scriptPath('generate_cline_rules.py'), [CWD]);
|
|
390
|
+
run(scriptPath('generate_roo_rules.py'), [CWD]);
|
|
391
|
+
run(scriptPath('generate_augment_rules.py'), [CWD]);
|
|
392
|
+
// Single-file generators
|
|
393
|
+
const conventionsOut = runGenerator('generate_conventions.py');
|
|
394
|
+
fs.writeFileSync(path.join(CWD, 'CONVENTIONS.md'), conventionsOut);
|
|
395
|
+
console.log('Generated: CONVENTIONS.md');
|
|
375
396
|
generateLlmsTxt();
|
|
376
397
|
}
|
|
377
398
|
|
|
@@ -429,6 +450,13 @@ const SPECIAL_HANDLERS = {
|
|
|
429
450
|
'inject-hook': handleInjectHook,
|
|
430
451
|
'remove-hook': handleRemoveHook,
|
|
431
452
|
'llms-txt': (_args) => generateLlmsTxt(),
|
|
453
|
+
'antigravity-rules': (_args) => run(scriptPath('generate_antigravity.py'), [CWD]),
|
|
454
|
+
'cursor-mdc': (_args) => run(scriptPath('generate_cursor_mdc.py'), [CWD]),
|
|
455
|
+
'windsurf-dir-rules': (_args) => run(scriptPath('generate_windsurf_rules.py'), [CWD]),
|
|
456
|
+
'cline-dir-rules': (_args) => run(scriptPath('generate_cline_rules.py'), [CWD]),
|
|
457
|
+
'roo-dir-rules': (_args) => run(scriptPath('generate_roo_rules.py'), [CWD]),
|
|
458
|
+
'conventions-md': (_args) => { const out = runGenerator('generate_conventions.py'); fs.writeFileSync(path.join(CWD, 'CONVENTIONS.md'), out); console.log('Generated: CONVENTIONS.md'); },
|
|
459
|
+
'augment-dir-rules': (_args) => run(scriptPath('generate_augment_rules.py'), [CWD]),
|
|
432
460
|
'generate-all': handleGenerateAll,
|
|
433
461
|
};
|
|
434
462
|
|
|
@@ -0,0 +1,283 @@
|
|
|
1
|
+
---
|
|
2
|
+
title: "SOP: Release Verification"
|
|
3
|
+
category: procedures
|
|
4
|
+
service: ai-toolkit
|
|
5
|
+
tags: [sop, verification, release, smoke-test, install, update, qa]
|
|
6
|
+
version: "1.1.0"
|
|
7
|
+
created: "2026-04-08"
|
|
8
|
+
last_updated: "2026-04-08"
|
|
9
|
+
description: "End-to-end smoke test after installing or updating @softspark/ai-toolkit — verifies CLI, install, doctor, validation, tests, and eject from user perspective."
|
|
10
|
+
---
|
|
11
|
+
|
|
12
|
+
# SOP: Release Verification
|
|
13
|
+
|
|
14
|
+
End-to-end smoke test after installing or updating `@softspark/ai-toolkit`.
|
|
15
|
+
Verifies all critical paths from the user's perspective.
|
|
16
|
+
|
|
17
|
+
**Use this SOP when:**
|
|
18
|
+
- After `npm install -g @softspark/ai-toolkit@latest`
|
|
19
|
+
- After `ai-toolkit update`
|
|
20
|
+
- Before tagging a new version (`git tag`)
|
|
21
|
+
- Before publishing to npm (`npm publish`)
|
|
22
|
+
- As a smoke test in CI/CD
|
|
23
|
+
|
|
24
|
+
**Prerequisites:**
|
|
25
|
+
- Node.js >= 18, Python 3, `bats`, git
|
|
26
|
+
- `@softspark/ai-toolkit` installed globally
|
|
27
|
+
|
|
28
|
+
**Time:** 10-15 minutes (full), 2 minutes (quick checklist)
|
|
29
|
+
|
|
30
|
+
---
|
|
31
|
+
|
|
32
|
+
## Quick Checklist (TL;DR)
|
|
33
|
+
|
|
34
|
+
9 commands — if all pass, the release is ready:
|
|
35
|
+
|
|
36
|
+
```bash
|
|
37
|
+
# Pre-commit (Phase 0)
|
|
38
|
+
python3 scripts/generate_agents_md.py > AGENTS.md # 1. Regenerate artifacts
|
|
39
|
+
python3 scripts/generate_llms_txt.py > llms.txt # 2. Regenerate llms.txt
|
|
40
|
+
python3 scripts/validate.py --strict # 3. Validation passed?
|
|
41
|
+
npm test # 4. All tests passed?
|
|
42
|
+
|
|
43
|
+
# Post-install verification (Phases 1-7)
|
|
44
|
+
ai-toolkit --version # 5. Version OK?
|
|
45
|
+
ai-toolkit status # 6. Status OK?
|
|
46
|
+
ai-toolkit doctor # 7. Health check passed?
|
|
47
|
+
ai-toolkit install --dry-run # 8. Global install OK?
|
|
48
|
+
python3 scripts/audit_skills.py --ci # 9. Security audit clean?
|
|
49
|
+
```
|
|
50
|
+
|
|
51
|
+
---
|
|
52
|
+
|
|
53
|
+
## Phase 0: Pre-Commit & Pre-Push (2 min)
|
|
54
|
+
|
|
55
|
+
Run these commands **before every commit and push to main**. CI validates
|
|
56
|
+
counts but does NOT auto-regenerate — you must do it locally.
|
|
57
|
+
|
|
58
|
+
```bash
|
|
59
|
+
# 1. Regenerate generated artifacts
|
|
60
|
+
python3 scripts/generate_agents_md.py > AGENTS.md
|
|
61
|
+
python3 scripts/generate_llms_txt.py > llms.txt
|
|
62
|
+
python3 scripts/generate_llms_txt.py --full > llms-full.txt
|
|
63
|
+
|
|
64
|
+
# 2. Validate everything (catches stale counts, missing assets)
|
|
65
|
+
python3 scripts/validate.py --strict
|
|
66
|
+
|
|
67
|
+
# 3. Security audit
|
|
68
|
+
python3 scripts/audit_skills.py --ci
|
|
69
|
+
|
|
70
|
+
# 4. Run tests
|
|
71
|
+
npm test
|
|
72
|
+
|
|
73
|
+
# 5. Stage and commit
|
|
74
|
+
git add AGENTS.md llms.txt llms-full.txt
|
|
75
|
+
git add -p # stage your other changes
|
|
76
|
+
git commit -m "feat: your change description"
|
|
77
|
+
```
|
|
78
|
+
|
|
79
|
+
**Why local?** Branch protection on `main` requires PRs and status checks.
|
|
80
|
+
CI cannot push directly to `main`, so generated artifacts must be committed
|
|
81
|
+
by the developer as part of their PR.
|
|
82
|
+
|
|
83
|
+
**One-liner (copy-paste):**
|
|
84
|
+
```bash
|
|
85
|
+
python3 scripts/generate_agents_md.py > AGENTS.md && python3 scripts/generate_llms_txt.py > llms.txt && python3 scripts/generate_llms_txt.py --full > llms-full.txt && python3 scripts/validate.py --strict && python3 scripts/audit_skills.py --ci && npm test
|
|
86
|
+
```
|
|
87
|
+
|
|
88
|
+
---
|
|
89
|
+
|
|
90
|
+
## Phase 1: CLI & Version (1 min)
|
|
91
|
+
|
|
92
|
+
```bash
|
|
93
|
+
ai-toolkit --version
|
|
94
|
+
ai-toolkit --help
|
|
95
|
+
which ai-toolkit
|
|
96
|
+
```
|
|
97
|
+
|
|
98
|
+
**Verify:**
|
|
99
|
+
- [ ] `--version` returns correct semver (e.g., `1.4.0`)
|
|
100
|
+
- [ ] `--help` displays full command list without errors
|
|
101
|
+
- [ ] `which` points to global npm bin path
|
|
102
|
+
|
|
103
|
+
---
|
|
104
|
+
|
|
105
|
+
## Phase 2: Global Install & Status (2 min)
|
|
106
|
+
|
|
107
|
+
```bash
|
|
108
|
+
ai-toolkit install --dry-run
|
|
109
|
+
ai-toolkit status
|
|
110
|
+
```
|
|
111
|
+
|
|
112
|
+
**Verify `--dry-run`:**
|
|
113
|
+
- [ ] Agents >= 40
|
|
114
|
+
- [ ] Skills >= 80
|
|
115
|
+
- [ ] Hooks merged into settings.json
|
|
116
|
+
- [ ] "Other AI Tools" section lists cursor, windsurf, gemini, augment (antigravity via --local)
|
|
117
|
+
|
|
118
|
+
**Verify `status`:**
|
|
119
|
+
- [ ] Version matches expected
|
|
120
|
+
- [ ] Profile: minimal/standard/strict
|
|
121
|
+
- [ ] Modules: list of installed modules
|
|
122
|
+
- [ ] Latest: up to date / update available
|
|
123
|
+
|
|
124
|
+
---
|
|
125
|
+
|
|
126
|
+
## Phase 3: Doctor Health Check (1 min)
|
|
127
|
+
|
|
128
|
+
```bash
|
|
129
|
+
ai-toolkit doctor
|
|
130
|
+
```
|
|
131
|
+
|
|
132
|
+
**Expected sections (all OK):**
|
|
133
|
+
- Environment: node, bash, python3, bats
|
|
134
|
+
- Global Install: .claude exists, agents/skills symlinks (0 broken), settings.json hooks
|
|
135
|
+
- Hook Scripts: all present and executable
|
|
136
|
+
- Hook Configuration: 12 events registered
|
|
137
|
+
- Generated Artifacts: AGENTS.md, llms.txt, llms-full.txt
|
|
138
|
+
- Planned Assets: plugin.json, benchmarks, plugin packs
|
|
139
|
+
- Benchmark Freshness: < 30 days
|
|
140
|
+
- Stale Rules: all healthy
|
|
141
|
+
|
|
142
|
+
**Verify:**
|
|
143
|
+
- [ ] `Errors: 0 | Warnings: 0`
|
|
144
|
+
- [ ] `HEALTH CHECK PASSED`
|
|
145
|
+
|
|
146
|
+
If doctor detects problems: `ai-toolkit doctor --fix` auto-repairs
|
|
147
|
+
(broken symlinks, non-executable hooks, missing scripts, missing llms-full.txt).
|
|
148
|
+
|
|
149
|
+
---
|
|
150
|
+
|
|
151
|
+
## Phase 4: Local Install (2 min)
|
|
152
|
+
|
|
153
|
+
```bash
|
|
154
|
+
mkdir -p /tmp/ai-toolkit-verify && cd /tmp/ai-toolkit-verify
|
|
155
|
+
git init -q
|
|
156
|
+
ai-toolkit install --local --editors all --dry-run
|
|
157
|
+
cd - && rm -rf /tmp/ai-toolkit-verify
|
|
158
|
+
```
|
|
159
|
+
|
|
160
|
+
**Verify "Project-local" section:**
|
|
161
|
+
- [ ] Would create: CLAUDE.md
|
|
162
|
+
- [ ] Would create: .claude/settings.local.json
|
|
163
|
+
- [ ] Would inject: .claude/constitution.md
|
|
164
|
+
- [ ] Editors: all 8 listed (copilot, cursor, windsurf, cline, roo, aider, augment, antigravity)
|
|
165
|
+
- [ ] Would generate configs for each editor (legacy + directory-based)
|
|
166
|
+
- [ ] Would install: .git/hooks/pre-commit
|
|
167
|
+
- [ ] Would inject language rules (auto-detected)
|
|
168
|
+
|
|
169
|
+
**Also test auto-detect (no --editors flag):**
|
|
170
|
+
```bash
|
|
171
|
+
ai-toolkit install --local --dry-run
|
|
172
|
+
# → Editors: none (empty project has no existing configs)
|
|
173
|
+
```
|
|
174
|
+
|
|
175
|
+
---
|
|
176
|
+
|
|
177
|
+
## Phase 5: Validation & Security Audit (3 min)
|
|
178
|
+
|
|
179
|
+
```bash
|
|
180
|
+
python3 scripts/validate.py --strict
|
|
181
|
+
python3 scripts/audit_skills.py --ci
|
|
182
|
+
```
|
|
183
|
+
|
|
184
|
+
**Verify validate.py:**
|
|
185
|
+
- [ ] Agents >= 40, Skills >= 80, Tests >= 350
|
|
186
|
+
- [ ] Hook events: 12, Hook scripts: >= 20
|
|
187
|
+
- [ ] Plugin packs >= 10, KB documents >= 20
|
|
188
|
+
- [ ] `Errors: 0 | Warnings: 0` → `VALIDATION PASSED`
|
|
189
|
+
|
|
190
|
+
**Verify audit_skills.py:**
|
|
191
|
+
- [ ] `HIGH: 0` (MUST be zero — CI fails otherwise)
|
|
192
|
+
- [ ] `WARN: 0`
|
|
193
|
+
- [ ] `INFO: N` (acceptable — broad-access skills: orchestrate, swarm, teams)
|
|
194
|
+
|
|
195
|
+
---
|
|
196
|
+
|
|
197
|
+
## Phase 6: Tests (3-5 min)
|
|
198
|
+
|
|
199
|
+
```bash
|
|
200
|
+
npm test
|
|
201
|
+
```
|
|
202
|
+
|
|
203
|
+
**Verify:**
|
|
204
|
+
- [ ] Bats runs tests in parallel (4 jobs)
|
|
205
|
+
- [ ] All `ok` — zero `not ok`
|
|
206
|
+
- [ ] Groups: agents, autodetect, cli, generators, guards, hooks, inject,
|
|
207
|
+
install, kb, mcp, readme, profiles, uninstall, validate
|
|
208
|
+
|
|
209
|
+
**Key test areas:**
|
|
210
|
+
- Guards: rm -rf, DROP TABLE, git push --force blocked
|
|
211
|
+
- Install: idempotent, profiles, --only/--skip, orphan cleanup
|
|
212
|
+
- Eject: real files (not symlinks), inlined rules
|
|
213
|
+
- Uninstall: removes toolkit, preserves user content
|
|
214
|
+
|
|
215
|
+
---
|
|
216
|
+
|
|
217
|
+
## Phase 7: Eject (1 min)
|
|
218
|
+
|
|
219
|
+
```bash
|
|
220
|
+
mkdir -p /tmp/ai-toolkit-eject-test
|
|
221
|
+
cd /tmp/ai-toolkit-eject-test
|
|
222
|
+
ai-toolkit eject
|
|
223
|
+
cd - && rm -rf /tmp/ai-toolkit-eject-test
|
|
224
|
+
```
|
|
225
|
+
|
|
226
|
+
**Verify:**
|
|
227
|
+
- [ ] Agents copied as real files (not symlinks)
|
|
228
|
+
- [ ] Skills copied as real directories
|
|
229
|
+
- [ ] Rules inlined into CLAUDE.md
|
|
230
|
+
- [ ] constitution.md and ARCHITECTURE.md copied
|
|
231
|
+
|
|
232
|
+
---
|
|
233
|
+
|
|
234
|
+
## Troubleshooting
|
|
235
|
+
|
|
236
|
+
### `ai-toolkit: command not found`
|
|
237
|
+
|
|
238
|
+
```bash
|
|
239
|
+
npm install -g @softspark/ai-toolkit
|
|
240
|
+
# or check PATH:
|
|
241
|
+
export PATH="$(npm config get prefix)/bin:$PATH"
|
|
242
|
+
```
|
|
243
|
+
|
|
244
|
+
### Doctor: broken symlinks
|
|
245
|
+
|
|
246
|
+
```bash
|
|
247
|
+
ai-toolkit doctor --fix # auto-repair
|
|
248
|
+
ai-toolkit update # or full re-install
|
|
249
|
+
```
|
|
250
|
+
|
|
251
|
+
### Tests fail: missing bats
|
|
252
|
+
|
|
253
|
+
```bash
|
|
254
|
+
brew install bats-core # macOS
|
|
255
|
+
npm install -g bats # cross-platform
|
|
256
|
+
```
|
|
257
|
+
|
|
258
|
+
### validate.py: stale counts
|
|
259
|
+
|
|
260
|
+
README badges don't match the current agents/skills/tests counts.
|
|
261
|
+
Update README.md and re-run.
|
|
262
|
+
|
|
263
|
+
### Eject: missing skills
|
|
264
|
+
|
|
265
|
+
```bash
|
|
266
|
+
ai-toolkit update # re-link missing symlinks
|
|
267
|
+
ai-toolkit eject /tmp/test # retry
|
|
268
|
+
```
|
|
269
|
+
|
|
270
|
+
---
|
|
271
|
+
|
|
272
|
+
## Success Criteria
|
|
273
|
+
|
|
274
|
+
| Area | Criterion |
|
|
275
|
+
|------|-----------|
|
|
276
|
+
| CLI | `--version` correct, `--help` full list, `status` current |
|
|
277
|
+
| Health | `doctor`: 0 errors, 0 warnings, PASSED |
|
|
278
|
+
| Install | `--dry-run` correct counts, `--local` all configs |
|
|
279
|
+
| Quality | `validate.py --strict`: PASSED |
|
|
280
|
+
| Security | `audit_skills.py --ci`: 0 HIGH |
|
|
281
|
+
| Tests | `npm test`: N/N passed, 0 failures |
|
|
282
|
+
| Eject | Standalone .claude/ with real files |
|
|
283
|
+
| Guards | Destructive commands blocked |
|
|
@@ -3,7 +3,7 @@ title: "AI Toolkit - Architecture Overview"
|
|
|
3
3
|
category: reference
|
|
4
4
|
service: ai-toolkit
|
|
5
5
|
tags: [architecture, overview, design, structure]
|
|
6
|
-
version: "1.
|
|
6
|
+
version: "1.4.0"
|
|
7
7
|
created: "2026-03-23"
|
|
8
8
|
last_updated: "2026-04-08"
|
|
9
9
|
description: "Architecture of ai-toolkit: directory layout, global install model, skill tiers, and integration with projects."
|
|
@@ -13,7 +13,7 @@ description: "Architecture of ai-toolkit: directory layout, global install model
|
|
|
13
13
|
|
|
14
14
|
## Purpose
|
|
15
15
|
|
|
16
|
-
Shared, project-agnostic AI development toolkit for Claude Code (and compatible assistants like Cursor, Windsurf, Copilot, Gemini, Cline, Roo Code, Aider, and
|
|
16
|
+
Shared, project-agnostic AI development toolkit for Claude Code (and compatible assistants like Cursor, Windsurf, Copilot, Gemini, Cline, Roo Code, Aider, Augment, and Google Antigravity). Provides specialized agents, 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.
|
|
17
17
|
|
|
18
18
|
## Design Principles
|
|
19
19
|
|
|
@@ -103,14 +103,19 @@ Machine (global) Project (local)
|
|
|
103
103
|
|
|
104
104
|
**`ai-toolkit update`** — re-apply after `npm install -g @softspark/ai-toolkit@latest` or after `add-rule` / `remove-rule`. Same as `install` but semantically correct for update flows.
|
|
105
105
|
|
|
106
|
-
**`ai-toolkit install --local`**
|
|
106
|
+
**`ai-toolkit install --local`** — run per project. Always installs Claude Code configs (CLAUDE.md, settings.local.json, constitution.md, language rules). Editor configs are opt-in via `--editors`:
|
|
107
|
+
- `--editors all` — install all 8 editors (Cursor, Windsurf, Cline, Roo, Aider, Augment, Copilot, Antigravity)
|
|
108
|
+
- `--editors cursor,aider` — install only selected editors
|
|
109
|
+
- (no flag) — auto-detect from existing project files; `update --local` picks up whatever editors already have configs
|
|
110
|
+
|
|
111
|
+
Each editor gets both legacy single-file format (for backwards compat) and new directory-based format (`.cursor/rules/*.mdc`, `.windsurf/rules/*.md`, `.cline/rules/*.md`, `.roo/rules/*.md`, `.augment/rules/ai-toolkit-*.md`, `.agent/rules/*.md`, `CONVENTIONS.md`). Hooks are global-only — not merged into project settings.
|
|
107
112
|
|
|
108
113
|
## CLI Commands
|
|
109
114
|
|
|
110
115
|
| Command | Target | What it does |
|
|
111
116
|
|---------|--------|-------------|
|
|
112
117
|
| `install` | `~/.claude/` | First-time: per-file symlinks + JSON merge + marker injection + rules |
|
|
113
|
-
| `install --local` | `./` |
|
|
118
|
+
| `install --local` | `./` | Claude Code configs + editors via `--editors` (auto-detect or explicit) |
|
|
114
119
|
| `update` | `~/.claude/` | Re-apply after npm update or after add-rule/remove-rule |
|
|
115
120
|
| `update --local` | `./` | Re-apply + refresh project-local configs |
|
|
116
121
|
| `uninstall` | `~/.claude/` | Strips toolkit components (preserves user content) |
|
|
@@ -120,13 +125,20 @@ Machine (global) Project (local)
|
|
|
120
125
|
| `doctor` | toolkit | Install health, hooks, benchmark freshness, and artifact drift diagnostics |
|
|
121
126
|
| `benchmark-ecosystem` | toolkit | Benchmark snapshot for official Claude Code and external ecosystem repos |
|
|
122
127
|
| `evaluate` | toolkit | Skill quality report |
|
|
123
|
-
| `cursor-rules` | `./` | Generates `.cursorrules` |
|
|
124
|
-
| `
|
|
128
|
+
| `cursor-rules` | `./` | Generates `.cursorrules` (legacy) |
|
|
129
|
+
| `cursor-mdc` | `./` | Generates `.cursor/rules/*.mdc` (recommended) |
|
|
130
|
+
| `windsurf-rules` | `./` | Generates `.windsurfrules` (legacy) |
|
|
131
|
+
| `windsurf-dir-rules` | `./` | Generates `.windsurf/rules/*.md` |
|
|
125
132
|
| `copilot-instructions` | `./` | Generates `.github/copilot-instructions.md` |
|
|
126
133
|
| `gemini-md` | `./` | Generates `GEMINI.md` |
|
|
127
|
-
| `cline-rules` | `./` | Generates `.clinerules` |
|
|
134
|
+
| `cline-rules` | `./` | Generates `.clinerules` (legacy) |
|
|
135
|
+
| `cline-dir-rules` | `./` | Generates `.cline/rules/*.md` |
|
|
128
136
|
| `roo-modes` | `./` | Generates `.roomodes` |
|
|
137
|
+
| `roo-dir-rules` | `./` | Generates `.roo/rules/*.md` |
|
|
129
138
|
| `aider-conf` | `./` | Generates `.aider.conf.yml` |
|
|
139
|
+
| `conventions-md` | `./` | Generates `CONVENTIONS.md` (Aider auto-loaded) |
|
|
140
|
+
| `augment-dir-rules` | `./` | Generates `.augment/rules/ai-toolkit-*.md` |
|
|
141
|
+
| `antigravity-rules` | `./` | Generates `.agent/rules/` + `.agent/workflows/` |
|
|
130
142
|
| `agents-md` | toolkit | Regenerates `AGENTS.md` |
|
|
131
143
|
| `llms-txt` | `./` | Generates `llms.txt` |
|
|
132
144
|
| `generate-all` | `./` | Generates all platform configs at once |
|
|
@@ -178,6 +190,23 @@ Skills that spawn real parallel agents use:
|
|
|
178
190
|
|
|
179
191
|
`CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1` must be set for Agent Teams (tmux-based) support.
|
|
180
192
|
|
|
193
|
+
## Quality Guardrails
|
|
194
|
+
|
|
195
|
+
### Anti-Rationalization Tables
|
|
196
|
+
15 core skills include `## Common Rationalizations` tables — domain-specific excuses with rebuttals that prevent agent drift. Skills: `/review`, `/debug`, `/refactor`, `/tdd`, `/plan`, `/docs`, `/analyze`, `security-patterns`, `testing-patterns`, `api-patterns`, `ci-cd-patterns`, `clean-code`, `performance-profiling`, `git-mastery`, `database-patterns`.
|
|
197
|
+
|
|
198
|
+
### Confidence Scoring & LLM-as-Judge (`/review`)
|
|
199
|
+
Review findings include per-issue confidence scores (1-10) and severity tiers (critical/major/minor/nit). A self-evaluation pass after review checks for anchoring bias, assumption vs verification, and calibrates confidence.
|
|
200
|
+
|
|
201
|
+
### Agent Verification Checklists
|
|
202
|
+
10 agents have `## Verification Checklist` — domain-specific exit criteria: `code-reviewer`, `test-engineer`, `security-auditor`, `debugger`, `backend-specialist`, `frontend-specialist`, `database-architect`, `performance-optimizer`, `devops-implementer`, `documenter`.
|
|
203
|
+
|
|
204
|
+
### Skill Reference Routing
|
|
205
|
+
7 core skills include `## Related Skills` suggesting follow-up skills: `/review`, `/debug`, `/plan`, `/refactor`, `/tdd`, `/docs`, `/analyze`.
|
|
206
|
+
|
|
207
|
+
### Intent Capture Interview (`/onboard`)
|
|
208
|
+
Step 0 interview — 5 questions to capture undocumented project intent before setup.
|
|
209
|
+
|
|
181
210
|
## Component Relationships
|
|
182
211
|
|
|
183
212
|
```
|