@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.
Files changed (49) hide show
  1. package/CHANGELOG.md +41 -0
  2. package/README.md +62 -16
  3. package/app/agents/backend-specialist.md +8 -0
  4. package/app/agents/code-reviewer.md +9 -0
  5. package/app/agents/database-architect.md +8 -0
  6. package/app/agents/debugger.md +8 -0
  7. package/app/agents/devops-implementer.md +8 -0
  8. package/app/agents/documenter.md +8 -0
  9. package/app/agents/frontend-specialist.md +8 -0
  10. package/app/agents/performance-optimizer.md +8 -0
  11. package/app/agents/security-auditor.md +9 -0
  12. package/app/agents/test-engineer.md +9 -0
  13. package/app/skills/analyze/SKILL.md +15 -0
  14. package/app/skills/api-patterns/SKILL.md +10 -0
  15. package/app/skills/ci-cd-patterns/SKILL.md +10 -0
  16. package/app/skills/clean-code/SKILL.md +10 -0
  17. package/app/skills/database-patterns/SKILL.md +10 -0
  18. package/app/skills/debug/SKILL.md +16 -0
  19. package/app/skills/docs/SKILL.md +16 -0
  20. package/app/skills/git-mastery/SKILL.md +10 -0
  21. package/app/skills/onboard/SKILL.md +15 -0
  22. package/app/skills/performance-profiling/SKILL.md +10 -0
  23. package/app/skills/plan/SKILL.md +16 -0
  24. package/app/skills/refactor/SKILL.md +16 -0
  25. package/app/skills/review/SKILL.md +58 -3
  26. package/app/skills/security-patterns/SKILL.md +10 -0
  27. package/app/skills/tdd/SKILL.md +6 -0
  28. package/app/skills/testing-patterns/SKILL.md +10 -0
  29. package/bin/ai-toolkit.js +33 -5
  30. package/kb/procedures/release-verification-sop.md +283 -0
  31. package/kb/reference/architecture-overview.md +36 -7
  32. package/kb/reference/competitive-features-implementation.md +51 -52
  33. package/kb/reference/language-rules.md +18 -4
  34. package/kb/reference/skills-catalog.md +57 -1
  35. package/llms-full.txt +451 -64
  36. package/llms.txt +1 -0
  37. package/manifest.json +1 -1
  38. package/package.json +4 -2
  39. package/scripts/dir_rules_shared.py +441 -0
  40. package/scripts/generate_antigravity.py +36 -0
  41. package/scripts/generate_augment_rules.py +107 -0
  42. package/scripts/generate_cline_rules.py +31 -0
  43. package/scripts/generate_conventions.py +37 -0
  44. package/scripts/generate_cursor_mdc.py +127 -0
  45. package/scripts/generate_roo_rules.py +30 -0
  46. package/scripts/generate_windsurf_rules.py +31 -0
  47. package/scripts/install.py +26 -1
  48. package/scripts/install_steps/ai_tools.py +149 -31
  49. 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
- - [explanation]
126
+ - Severity: critical | Confidence: [1-10]
127
+ - Evidence: [specific code reference and reasoning]
126
128
  - Suggested fix: [code]
127
129
 
128
- #### Suggestions
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
- - [explanation]
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).
@@ -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
- 'windsurf-rules': 'Generate .windsurfrules for Windsurf',
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
- 'augment-rules': 'Generate .augment/rules/ai-toolkit.md for Augment',
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.3.14"
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 Augment). 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.
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`** (or `update --local`) — run per project, creates `CLAUDE.md` template + `.claude/settings.local.json` (only if missing, initialized with MCP defaults), and injects `constitution.md` + Copilot + Cline + Roo Code + Aider configs into local `.claude/` (preserves existing user content). Installs `--local` git hooks as a fallback for quality gates. Hooks are global-only not merged into project settings.
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` | `./` | Also set up project-local: `CLAUDE.md` + `settings.local.json` + constitution + Copilot + Cline + Roo + Aider + Git Hooks (hooks stay global-only) |
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
- | `windsurf-rules` | `./` | Generates `.windsurfrules` |
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
  ```