@softspark/ai-toolkit 1.3.14 → 1.4.0

package/CHANGELOG.md

@@ -7,6 +7,47 @@ Versioning follows [Semantic Versioning](https://semver.org/).
 
 ---
 
+## v1.4.0 — Full Platform Parity: 11 Editors, Directory-Based Rules, --editors Flag (2026-04-09)
+
+### Added
+- **Google Antigravity support** — new editor integration with `.agent/rules/` (6 rule files) and `.agent/workflows/` (13 workflow templates with YAML frontmatter). Full agent/skill catalog parity with other platforms.
+- **Directory-based rules for all editors** — every platform now gets modern directory-based configs in addition to legacy single-file formats:
+  - Cursor: `.cursor/rules/*.mdc` with YAML frontmatter (`alwaysApply`, `globs`, `description`)
+  - Windsurf: `.windsurf/rules/*.md`
+  - Cline: `.cline/rules/*.md`
+  - Roo Code: `.roo/rules/*.md` (shared rules for all modes)
+  - Augment: `.augment/rules/ai-toolkit-*.md` with `auto_attached` globs per file type
+  - Aider: `CONVENTIONS.md` (auto-loaded as read-only context)
+- **`--editors` flag** for `install --local` — selective editor installation:
+  - `--editors all` — install all 8 editors
+  - `--editors cursor,aider` — install only selected
+  - (no flag) — auto-detect from existing project files
+  - `update --local` auto-detects editors from existing configs
+- **`--lang` flag** — explicit language selection for rules (`--lang typescript`, `--lang go,python`) with aliases (`go`→`golang`, `c++`→`cpp`, `cs`→`csharp`)
+- **Two-phase language detection** — marker files (package.json, go.mod, etc.) + source file extension scanning (.py, .ts, .go, etc.)
+- **Shared rule content module** (`dir_rules_shared.py`) — all platforms get identical agent/skill catalog, guidelines, and rules from a single source of truth
+- **7 new CLI commands**: `cursor-mdc`, `windsurf-dir-rules`, `cline-dir-rules`, `roo-dir-rules`, `augment-dir-rules`, `conventions-md`, `antigravity-rules`
+- **71 generator tests** — file existence, content verification, user file preservation, idempotency, stale cleanup, cross-platform parity check
+
+### Changed
+- `install --local` now installs only Claude Code configs by default (no editor bloat); editors require `--editors` flag or auto-detect from existing files
+- All directory-based generators use `ai-toolkit-` prefix to prevent overwriting user files
+- Total test count: 377 → 408
+
+---
+
+## v1.3.15 — Quality Guardrails: Anti-Rationalization, Confidence Scoring, Verification Checklists (2026-04-08)
+
+### Added
+- **Anti-rationalization tables** — 15 core skills now include `## Common Rationalizations` sections with domain-specific excuse/rebuttal tables that prevent agent drift and shortcut-taking. Inspired by [addyosmani/agent-skills](https://github.com/addyosmani/agent-skills).
+- **Confidence scoring** (`/review`) — review findings now include per-issue confidence scores (1-10) and severity classification (critical/major/minor/nit) with a calibration guide.
+- **LLM-as-Judge self-evaluation** (`/review`) — structured self-check after review: blind spot detection, anchoring bias check, and confidence calibration.
+- **Agent verification checklists** — 10 key agents (`code-reviewer`, `test-engineer`, `security-auditor`, `debugger`, `backend-specialist`, `frontend-specialist`, `database-architect`, `performance-optimizer`, `devops-implementer`, `documenter`) now include `## Verification Checklist` exit criteria.
+- **Skill reference routing** — 7 core skills (`/review`, `/debug`, `/plan`, `/refactor`, `/tdd`, `/docs`, `/analyze`) include `## Related Skills` sections for follow-up discoverability.
+- **Intent Capture Interview** (`/onboard`) — Step 0 interview phase with 5 targeted questions to capture undocumented project intent before setup.
+
+---
+
 ## v1.3.14 — CVE Scanner + Open Contributions (2026-04-08)
 
 ### Added

package/README.md

@@ -1,12 +1,12 @@
 # ai-toolkit
 
-> Professional-grade AI coding toolkit with multi-platform support. Machine-enforced safety, 91 skills, 44 agents, expanded lifecycle hooks, persona presets, experimental opt-in plugin packs, and benchmark tooling — works with Claude, Cursor, Windsurf, Copilot, Gemini, Cline, Roo Code, Aider, and Augment, ready in 60 seconds.
+> Professional-grade AI coding toolkit with multi-platform support. Machine-enforced safety, 91 skills, 44 agents, expanded lifecycle hooks, persona presets, experimental opt-in plugin packs, and benchmark tooling — works with Claude, Cursor, Windsurf, Copilot, Gemini, Cline, Roo Code, Aider, Augment, and Google Antigravity, ready in 60 seconds.
 
 [![CI](https://github.com/softspark/ai-toolkit/actions/workflows/ci.yml/badge.svg)](https://github.com/softspark/ai-toolkit/actions/workflows/ci.yml)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
 [![Skills](https://img.shields.io/badge/skills-91-brightgreen)](app/skills/)
 [![Agents](https://img.shields.io/badge/agents-44-blue)](app/agents/)
-[![Tests](https://img.shields.io/badge/tests-377%20passing-success)](tests/)
+[![Tests](https://img.shields.io/badge/tests-408%20passing-success)](tests/)
 
 ---
 
@@ -112,20 +112,21 @@ Replaces all symlinks with real files, inlines rules into CLAUDE.md, copies cons
 
 ## Platform Support
 
-| Platform | Config File | How | Scope |
-|----------|------------|-----|-------|
+| Platform | Config Files | How | Scope |
+|----------|-------------|-----|-------|
 | Claude Code | `~/.claude/` | `ai-toolkit install` | global |
-| Cursor | `~/.cursor/rules` | `ai-toolkit install` | global |
-| Windsurf | `~/.codeium/windsurf/memories/global_rules.md` | `ai-toolkit install` | global |
+| Cursor | `~/.cursor/rules` + `.cursor/rules/*.mdc` | `ai-toolkit install` / `--local` | global + project |
+| Windsurf | `~/.codeium/.../global_rules.md` + `.windsurf/rules/*.md` | `ai-toolkit install` / `--local` | global + project |
 | Gemini CLI | `~/.gemini/GEMINI.md` | `ai-toolkit install` | global |
 | GitHub Copilot | `.github/copilot-instructions.md` | `ai-toolkit install --local` | project |
-| Cline | `.clinerules` | `ai-toolkit install --local` | project |
-| Roo Code | `.roomodes` | `ai-toolkit install --local` | project |
-| Aider | `.aider.conf.yml` | `ai-toolkit install --local` | project |
-| Augment | `.augment/rules/ai-toolkit.md` | `ai-toolkit install --local` | project |
+| Cline | `.clinerules` + `.cline/rules/*.md` | `ai-toolkit install --local` | project |
+| Roo Code | `.roomodes` + `.roo/rules/*.md` | `ai-toolkit install --local` | project |
+| Aider | `.aider.conf.yml` + `CONVENTIONS.md` | `ai-toolkit install --local` | project |
+| Augment | `.augment/rules/ai-toolkit-*.md` | `ai-toolkit install --local` | project |
+| Google Antigravity | `.agent/rules/*.md` + `.agent/workflows/*.md` | `ai-toolkit install --local` | project |
 | Codex / OpenCode | `AGENTS.md` | `ai-toolkit agents-md` | project |
 
-> **Note:** Claude Code remains the primary platform with full feature support (agents, lifecycle hooks, safety constitution). Other platforms receive a distilled ruleset generated from the same source. For editors lacking native bash lifecycle hooks, `--local` installs a Git hooks fallback (`.git/hooks/pre-commit`) to enforce quality gates pre-commit.
+> **Note:** Claude Code is always installed (primary platform with full feature support). Other editors are installed on demand with `--editors <list>` or auto-detected from existing project files. All platforms receive the same agent/skill catalog, guidelines, and rules. For editors lacking native bash lifecycle hooks, `--local` installs a Git hooks fallback (`.git/hooks/pre-commit`) to enforce quality gates pre-commit.
 
 ---
 
@@ -385,6 +386,43 @@ Three skills enforce non-negotiable quality gates with anti-rationalization tabl
 | `debugging-tactics` | `NO FIXES WITHOUT ROOT CAUSE INVESTIGATION FIRST` | 4-phase debugging: root cause → pattern → hypothesis → fix. 3+ failed fixes → question architecture. |
 | `verification-before-completion` | `NO COMPLETION CLAIMS WITHOUT FRESH VERIFICATION EVIDENCE` | Gate function: IDENTIFY → RUN → READ → VERIFY → CLAIM. "Should work now" is not evidence. |
 
+Additionally, **15 core skills** include `## Common Rationalizations` tables — domain-specific excuses with rebuttals that prevent agent drift and shortcut-taking. Skills with rationalization tables: `/review`, `/debug`, `/refactor`, `/tdd`, `/plan`, `/docs`, `/analyze`, `security-patterns`, `testing-patterns`, `api-patterns`, `ci-cd-patterns`, `clean-code`, `performance-profiling`, `git-mastery`, `database-patterns`.
+
+### Confidence Scoring & Self-Evaluation (`/review`)
+
+The `/review` skill outputs findings with per-issue confidence scores (1-10) and severity classification (critical/major/minor/nit). After completing a review, an LLM-as-Judge self-evaluation pass checks for blind spots: anchoring bias, assumption vs verification, missing unhappy paths, and calibrates confidence scores.
+
+### Agent Verification Checklists
+
+10 key agents include `## Verification Checklist` — exit criteria that MUST be met before presenting results. Each checklist is domain-specific:
+
+| Agent | Key exit criteria |
+|-------|------------------|
+| `code-reviewer` | Every finding has file:line + evidence, not just opinion |
+| `security-auditor` | Each finding includes proof-of-concept or exploit path |
+| `test-engineer` | No empty/placeholder tests, mocks only at boundaries |
+| `debugger` | Root cause identified, regression test added |
+| `backend-specialist` | Input validation, error format, query optimization |
+| `frontend-specialist` | Empty/loading/error states, accessibility, responsive |
+| `database-architect` | Migration tested on prod-like volume, rollback tested |
+| `performance-optimizer` | Baseline measured, profiler evidence attached |
+| `devops-implementer` | Dry run passed, rollback documented, no hardcoded secrets |
+| `documenter` | Code examples runnable, no placeholders, valid links |
+
+### Skill Reference Routing
+
+7 core skills include `## Related Skills` sections that suggest logical follow-up skills, improving discoverability:
+
+```
+/review → found issues? → /debug, /tdd, /cve-scan, /analyze
+/debug  → bug fixed?   → /review, /tdd, /workflow incident-response
+/plan   → approved?    → /orchestrate, /write-a-prd, /grill-me
+```
+
+### Intent Capture Interview (`/onboard`)
+
+The `/onboard` skill now includes a Step 0 interview phase before setup — asking 5 targeted questions to capture undocumented project intent (common contributor mistakes, protected files, deployment model, non-obvious constraints, review culture). Answers customize the generated `CLAUDE.md`.
+
 ### 7. Two-Stage Review (`/subagent-development`)
 
 Per-task review pipeline inspired by [obra/superpowers](https://github.com/obra/superpowers):
@@ -486,7 +524,7 @@ ai-toolkit install --local --lang typescript  # explicit language selection
 ai-toolkit install --local --lang go,python   # multiple languages
 ```
 
-`--local` automatically detects languages (via package.json, go.mod, Cargo.toml, etc.) — no need for `--auto-detect`. Rules are injected into `CLAUDE.md` and auto-updated on `ai-toolkit update --local`.
+`--local` automatically detects languages using two-phase detection: config markers (package.json, go.mod, Cargo.toml, etc.) plus source file extension scanning (.py, .ts, .go, etc.). `--lang` accepts aliases (`go`, `c++`, `cs`). Rules are injected into `CLAUDE.md` and auto-updated on `ai-toolkit update --local`.
 
 ---
 
@@ -722,7 +760,14 @@ Usage: ai-toolkit <command> [options]
 | `cline-rules` | Generate `.clinerules` in current dir |
 | `roo-modes` | Generate `.roomodes` in current dir |
 | `aider-conf` | Generate `.aider.conf.yml` in current dir |
-| `augment-rules` | Generate `.augment/rules/ai-toolkit.md` in current dir |
+| `conventions-md` | Generate `CONVENTIONS.md` for Aider (auto-loaded) |
+| `augment-rules` | Generate `.augment/rules/ai-toolkit.md` (legacy single file) |
+| `augment-dir-rules` | Generate `.augment/rules/ai-toolkit-*.md` (recommended) |
+| `cursor-mdc` | Generate `.cursor/rules/*.mdc` for Cursor (recommended) |
+| `windsurf-dir-rules` | Generate `.windsurf/rules/*.md` for Windsurf |
+| `cline-dir-rules` | Generate `.cline/rules/*.md` for Cline |
+| `roo-dir-rules` | Generate `.roo/rules/*.md` for Roo Code |
+| `antigravity-rules` | Generate `.agent/rules/` and `.agent/workflows/` for Google Antigravity |
 | `agents-md` | Regenerate `AGENTS.md` from agent definitions |
 | `llms-txt` | Generate `llms.txt` and `llms-full.txt` |
 | `generate-all` | Generate all platform configs at once |
@@ -735,11 +780,12 @@ ai-toolkit install --only agents,hooks   # apply only listed components
 ai-toolkit install --skip hooks          # skip listed components
 ai-toolkit install --profile minimal     # profile preset: minimal | standard | strict
 ai-toolkit install --persona backend-lead # persona preset: backend-lead | frontend-lead | devops-eng | junior-dev
-ai-toolkit install --local               # also set up project-local configs (CLAUDE.md, settings, constitution, Copilot, Cline, Roo, Aider, Git Hooks, MCP Defaults)
-ai-toolkit update --local                # re-apply + refresh project-local configs
+ai-toolkit install --local               # Claude Code only (CLAUDE.md, settings, constitution, language rules)
+ai-toolkit install --local --editors all # Claude Code + all editors (Cursor, Windsurf, Cline, Roo, Aider, Augment, Copilot, Antigravity)
+ai-toolkit install --local --editors cursor,aider  # Claude Code + specific editors
+ai-toolkit update --local                # re-apply; auto-detects editors from existing project files
 ai-toolkit install --list                # dry-run: show what would be applied
 ai-toolkit install --modules core,agents,rules-typescript  # selective module install
-ai-toolkit install --local               # auto-detects language, installs matching rules
 ai-toolkit install --lang typescript     # explicit language for rules install
 ```
 

package/app/agents/backend-specialist.md

@@ -184,6 +184,14 @@ After implementing significant changes, update documentation:
 ### Delegation
 For large documentation tasks, hand off to `documenter` agent.
 
+## Verification Checklist
+Before presenting implementation:
+- [ ] All new endpoints have input validation
+- [ ] Error responses follow the project's error format
+- [ ] Database queries are optimized (checked with EXPLAIN if applicable)
+- [ ] New dependencies are justified and audited
+- [ ] Migration is reversible
+
 ## KB Integration
 
 Before coding, search knowledge base:

package/app/agents/code-reviewer.md

@@ -177,6 +177,15 @@ After significant reviews, update documentation:
 ### Delegation
 For large documentation tasks, hand off to `documenter` agent.
 
+## Verification Checklist
+Before presenting review results:
+- [ ] Every finding includes file:line reference
+- [ ] Each finding has evidence (code snippet or reasoning), not just opinion
+- [ ] Severity rating reflects actual impact, not gut feeling
+- [ ] "No findings" includes list of specific checks performed
+- [ ] Security-sensitive files received deeper scrutiny
+- [ ] Test coverage gaps are flagged, not assumed covered
+
 ## Limitations
 
 - **Security penetration testing** → Use `security-auditor`

package/app/agents/database-architect.md

@@ -308,6 +308,14 @@ After schema/database changes, update documentation:
 ### Delegation
 For large documentation tasks, hand off to `documenter` agent.
 
+## Verification Checklist
+Before presenting schema changes:
+- [ ] Migration tested on production-like data volume
+- [ ] Rollback script exists and was tested
+- [ ] Indexes cover the expected query patterns
+- [ ] No long-running locks on large tables
+- [ ] Application handles both old and new schema during migration
+
 ## KB Integration
 
 Before designing, search knowledge base:

package/app/agents/debugger.md

@@ -231,6 +231,14 @@ After fixing significant bugs, update documentation:
 ### Delegation
 For large documentation tasks, hand off to `documenter` agent.
 
+## Verification Checklist
+Before claiming a bug is fixed:
+- [ ] Root cause identified, not just symptoms addressed
+- [ ] Fix was verified by reproducing the original failure first
+- [ ] Regression test added to prevent recurrence
+- [ ] Related code paths checked for similar issues
+- [ ] Fix doesn't introduce new side effects
+
 ## Limitations
 
 - **Performance profiling** → Use `performance-optimizer`

package/app/agents/devops-implementer.md

@@ -187,6 +187,14 @@ instructions: |
 ---
 ```
 
+## Verification Checklist
+Before presenting infrastructure changes:
+- [ ] Dry run completed successfully
+- [ ] Rollback procedure documented and tested
+- [ ] Secrets are not hardcoded or logged
+- [ ] Health checks configured for new services
+- [ ] Resource limits set to prevent runaway costs
+
 ## Limitations
 
 - **Architectural decisions** → Use `infrastructure-architect`

package/app/agents/documenter.md

@@ -357,6 +357,14 @@ last_updated: "YYYY-MM-DD"
 - Add diagrams where helpful
 - Version documentation with code
 
+## Verification Checklist
+Before presenting documentation:
+- [ ] Code examples are tested and runnable
+- [ ] No placeholder text or TODO markers remain
+- [ ] Links and references are valid
+- [ ] Architecture decisions include rationale (not just "what")
+- [ ] KB documents have complete YAML frontmatter
+
 ## Limitations
 
 - **Code implementation** → Use `devops-implementer`

package/app/agents/frontend-specialist.md

@@ -200,6 +200,14 @@ After implementing significant changes, update documentation:
 ### Delegation
 For large documentation tasks, hand off to `documenter` agent.
 
+## Verification Checklist
+Before presenting implementation:
+- [ ] Components render correctly with empty/loading/error states
+- [ ] Accessibility basics checked (keyboard nav, aria labels, contrast)
+- [ ] No console errors or warnings in dev tools
+- [ ] Responsive behavior verified at mobile/tablet/desktop breakpoints
+- [ ] Bundle size impact assessed for new dependencies
+
 ## KB Integration
 
 Before coding, search knowledge base:

package/app/agents/performance-optimizer.md

@@ -247,6 +247,14 @@ After performance optimizations, update documentation:
 ### Delegation
 For large documentation tasks, hand off to `documenter` agent.
 
+## Verification Checklist
+Before presenting optimization:
+- [ ] Baseline measurement taken before changes
+- [ ] Improvement measured with realistic data, not synthetic benchmarks
+- [ ] No regressions in other metrics (memory, latency, correctness)
+- [ ] Optimization targets the actual bottleneck (profiler evidence attached)
+- [ ] Cache invalidation strategy documented if caching was added
+
 ## Limitations
 
 - **Production incidents** → Use `incident-responder`

package/app/agents/security-auditor.md

@@ -301,6 +301,15 @@ For large documentation tasks, hand off to `documenter` agent.
 - No destructive testing without explicit approval
 - Report findings responsibly
 
+## Verification Checklist
+Before presenting security findings:
+- [ ] Each finding includes proof-of-concept or exploit path
+- [ ] Severity ratings reference actual impact, not theoretical risk
+- [ ] "No findings" includes the specific checks performed
+- [ ] Dependencies were scanned, not just application code
+- [ ] Secrets scan covered all file types (not just source code)
+- [ ] Auth flows were traced end-to-end, not spot-checked
+
 ## Limitations
 
 - **Code implementation** → Use `devops-implementer`

package/app/agents/test-engineer.md

@@ -257,6 +257,15 @@ After writing significant tests, update documentation:
 ### Delegation
 For large documentation tasks, hand off to `documenter` agent.
 
+## Verification Checklist
+Before presenting test results:
+- [ ] Every test has a clear assertion (no empty or placeholder tests)
+- [ ] Edge cases are explicitly tested, not assumed
+- [ ] Mocks are only at system boundaries, not internal collaborators
+- [ ] Test names describe behavior, not implementation
+- [ ] Flaky test patterns (time, network, order-dependent) are flagged
+- [ ] Coverage gaps are reported with specific uncovered paths
+
 ## Limitations
 
 - **Code implementation** → Use `devops-implementer`

package/app/skills/analyze/SKILL.md

@@ -82,6 +82,15 @@ python3 ${CLAUDE_SKILL_DIR}/scripts/complexity.py .
 
 Reports file counts by type, largest files, TODO/FIXME counts, and total code lines.
 
+## Common Rationalizations
+
+| Excuse | Why It's Wrong |
+|--------|----------------|
+| "The linter is green, the code is fine" | Linters catch syntax, not design flaws — analysis covers architecture and patterns |
+| "We know where the problems are" | Intuition misses systemic issues — data-driven analysis reveals hidden hotspots |
+| "Analysis takes too long" | A 5-minute scan prevents weeks of debugging — front-load the investment |
+| "It's legacy code, analysis won't help" | Legacy code benefits most — find the critical paths before they break |
+
 ## Tools Used
 
 | Language | Tools |
@@ -90,3 +99,9 @@ Reports file counts by type, largest files, TODO/FIXME counts, and total code li
 | JavaScript | eslint, tsc |
 | Go | golangci-lint |
 | Rust | clippy |
+
+## Related Skills
+- Found quality issues? → `/refactor` to fix them systematically
+- Security issues detected? → `/cve-scan` for dependency audit
+- Want deeper architecture review? → `/architecture-audit` for friction discovery
+- Performance hotspots found? → `/workflow performance-optimization`

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

@@ -292,6 +292,16 @@ Accept: application/vnd.myapi.v1+json
 
 ---
 
+## Common Rationalizations
+
+| Excuse | Why It's Wrong |
+|--------|----------------|
+| "We'll version the API later" | Unversioned APIs break clients on every change — version from day one |
+| "Retries are the client's problem" | Server-side idempotency prevents data corruption — design for at-least-once delivery |
+| "We'll add rate limiting later" | Unprotected endpoints get abused within hours of deployment |
+| "Error messages are just for debugging" | Error responses are your API's UX — clients depend on consistent, parseable errors |
+| "PATCH and PUT are the same thing" | PUT replaces the resource, PATCH modifies it — wrong semantics cause data loss |
+
 ## Best Practices
 
 - [ ] Use HTTPS only

package/app/skills/ci-cd-patterns/SKILL.md

@@ -291,6 +291,16 @@ env:
 | `feat:` | Minor (0.x.0) | `feat: add user search endpoint` |
 | `feat!:` / `BREAKING CHANGE:` | Major (x.0.0) | `feat!: change API response format` |
 
+## Common Rationalizations
+
+| Excuse | Why It's Wrong |
+|--------|----------------|
+| "CI is green, ship it" | CI tests the happy path — verify edge cases, security, and performance separately |
+| "Manual deploys give us more control" | Manual deploys give you more human error — automate the repeatable parts |
+| "We'll set up CI when the project is bigger" | Small projects grow fast — CI debt compounds and retrofitting is painful |
+| "Caching isn't worth the complexity" | Uncached builds waste developer time daily — caching pays for itself in a week |
+| "Feature flags are over-engineering" | Feature flags decouple deploy from release — they're the cheapest safety net |
+
 ## Anti-Patterns
 - Secrets in pipeline logs or environment dumps
 - No caching (slow builds)

package/app/skills/clean-code/SKILL.md

@@ -100,6 +100,16 @@ Keep modules focused. Order contents consistently: imports (stdlib, third-party,
 
 ---
 
+## Common Rationalizations
+
+| Excuse | Why It's Wrong |
+|--------|----------------|
+| "It's readable enough" | "Enough" means someone will misread it eventually — clarity prevents incidents |
+| "Refactoring for readability is gold-plating" | Readability is maintainability — future you will thank present you |
+| "Short variable names are faster to type" | You type it once, readers parse it hundreds of times — optimize for reading |
+| "DRY means never repeat anything" | Wrong DRY creates coupling — duplicate until you see the real abstraction |
+| "More abstractions = cleaner code" | Premature abstraction is worse than duplication — wait for the third use |
+
 ## Language-Specific References
 
 For detailed patterns, type hints, linting configuration, and idiomatic code per language:

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

@@ -296,3 +296,13 @@ client.create_payload_index(
 | COSINE | Text embeddings | Yes |
 | EUCLID | Image embeddings | No |
 | DOT | When vectors pre-normalized | Yes |
+
+## Common Rationalizations
+
+| Excuse | Why It's Wrong |
+|--------|----------------|
+| "We'll add indexes later when it's slow" | Missing indexes on production tables cause outages, not slowdowns — index from design |
+| "The ORM handles performance" | ORMs generate queries, they don't optimize them — always check the query plan |
+| "NoSQL is faster" | NoSQL trades consistency for speed — if you need joins, use a relational DB |
+| "We don't need migrations, we'll update the schema directly" | Direct schema changes are irreversible and untestable — migrations are the safety net |
+| "One big table is simpler" | Denormalization without measurement creates update anomalies — normalize first, denormalize with data |

package/app/skills/debug/SKILL.md

@@ -144,6 +144,16 @@ Have them talk to each other to challenge each other's theories.
 Report consensus when done.
 ```
 
+## Common Rationalizations
+
+| Excuse | Why It's Wrong |
+|--------|----------------|
+| "It works on my machine" | Environment differences are the #1 cause of production bugs — reproduce in prod-like env |
+| "It must be a library bug" | 95% of the time it's your code — exhaust local hypotheses first |
+| "I'll just add more logging and wait" | Passive debugging wastes hours — form a hypothesis and test it actively |
+| "The error message says X, so it must be X" | Error messages often describe symptoms, not root causes — trace the full chain |
+| "It only happens sometimes, probably a fluke" | Intermittent bugs are race conditions or state leaks — they get worse, not better |
+
 ## Debug Checklist
 
 - [ ] Identified error/symptom
@@ -152,3 +162,9 @@ Report consensus when done.
 - [ ] Reproduced issue
 - [ ] Formed hypothesis
 - [ ] Tested fix
+
+## Related Skills
+- Bug fixed? → `/review` to verify the fix quality
+- Need a regression test? → `/tdd` to write it test-first
+- Performance issue? → `/analyze --type=complexity` for hotspot analysis
+- Incident in production? → `/workflow incident-response` for full response

package/app/skills/docs/SKILL.md

@@ -113,6 +113,16 @@ Proposed
 - [ ] Commit changes
 ```
 
+## Common Rationalizations
+
+| Excuse | Why It's Wrong |
+|--------|----------------|
+| "The code is self-documenting" | Code shows how, not why — decisions, constraints, and context need prose |
+| "Nobody reads docs anyway" | People don't read bad docs — good docs are the first thing consulted |
+| "I'll document it when it's stable" | Unstable code needs docs most — document intent so others can contribute |
+| "Comments get stale" | That's an argument for maintaining docs, not skipping them |
+| "The tests are the documentation" | Tests verify behavior but don't explain architecture, trade-offs, or setup |
+
 ## Configuration
 
 Documentation settings in:
@@ -143,3 +153,9 @@ Create an agent team for documentation:
 - Teammate 3 (documenter): "Generate README sections: installation, usage, API reference." Use Opus.
 Teammates should NOT overlap — each owns their assigned scope.
 ```
+
+## Related Skills
+- Documenting an architecture decision? → `/council` for multi-perspective analysis first
+- Need to explore the codebase? → `/explore` to understand structure before documenting
+- Writing a PRD? → `/write-a-prd` for structured product requirements
+- Auditing existing docs? → `/analyze` for coverage gaps

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

@@ -68,3 +68,13 @@ git cherry-pick --continue
 - `perf:` Performance improvement
 - `test:` Adding missing tests
 - `chore:` Build process/auxiliary tools
+
+## Common Rationalizations
+
+| Excuse | Why It's Wrong |
+|--------|----------------|
+| "I'll clean up commits later" | Later means never — write clean commits as you go |
+| "Force push is fine on my branch" | Others may have fetched your branch — use --force-with-lease |
+| "One big commit is simpler" | Big commits are impossible to review, bisect, or revert — keep them atomic |
+| "Merge conflicts mean someone else's problem" | Conflicts mean you diverged too long — rebase frequently to stay aligned |
+| "Commit messages don't matter" | Messages are documentation — future you needs to understand why, not just what |

package/app/skills/onboard/SKILL.md

@@ -17,6 +17,21 @@ Guide the user through setting up the ai-toolkit in their project, including con
 
 ## Setup Steps
 
+### Step 0: Intent Capture Interview
+
+Before setting up tooling, understand the project's undocumented context. Ask the developer these questions (adapt based on what the codebase scan reveals):
+
+1. **What's the one thing a new contributor always gets wrong?** — This reveals the biggest documentation gap
+2. **Are there files or directories that should NOT be modified?** — Identifies protected areas (legacy, generated, vendor)
+3. **What's the deployment model?** — Monolith, microservices, serverless, edge — shapes which agents and skills are most relevant
+4. **Are there non-obvious constraints?** — Compliance requirements, performance budgets, browser support matrix
+5. **What's the team's review culture?** — Strict PR reviews, trunk-based, pair programming — configures `/review` behavior
+
+Use answers to:
+- Customize the generated `CLAUDE.md` with project-specific warnings and conventions
+- Select the right `--profile` (minimal/standard/strict) automatically
+- Pre-configure relevant language rules
+
 ### Step 1: Prerequisites Check
 - [ ] Claude Code CLI installed
 - [ ] ai-toolkit repository cloned

package/app/skills/performance-profiling/SKILL.md

@@ -57,3 +57,13 @@ Always measure -> change -> measure.
 2. **Algorithm**: (O(n²) -> O(n log n))
 3. **Memory**: (Allocation churn, GC pressure)
 4. **Micro-optimization**: (Loop unrolling, etc.) - *Smallest Gains*
+
+## Common Rationalizations
+
+| Excuse | Why It's Wrong |
+|--------|----------------|
+| "It feels slow, let me optimize this function" | Feelings aren't data — profile first, then optimize the actual bottleneck |
+| "We should optimize everything" | Premature optimization is the root of all evil — focus on the critical path |
+| "Caching will fix it" | Caching masks problems and adds complexity — fix the root cause first |
+| "It's fast enough in dev" | Dev has 1 user — production has thousands and cold caches |
+| "We'll optimize later" | Performance debt compounds — a 100ms regression per sprint = 5s in a year |

package/app/skills/plan/SKILL.md

@@ -95,6 +95,16 @@ During planning:
 - NO code writing
 - NO file creation (except plan)
 
+## Common Rationalizations
+
+| Excuse | Why It's Wrong |
+|--------|----------------|
+| "We already know what to build" | Assumed requirements lead to rework — validate assumptions explicitly |
+| "Planning is wasted time, just start coding" | Unplanned work has 3-5x more rework — 30 min planning saves days |
+| "The requirements will change anyway" | Plans adapt — without one, you can't assess impact of changes |
+| "It's a small feature, no plan needed" | Small features in complex systems have hidden dependencies — map them |
+| "We'll figure it out as we go" | Discovery without structure leads to scope creep and missed edge cases |
+
 ## Next Steps
 
 After plan approval:
@@ -108,3 +118,9 @@ Before planning:
 smart_query("project template: {type}")
 hybrid_search_kb("architecture {pattern}")
 ```
+
+## Related Skills
+- Plan approved? → `/orchestrate` or `/workflow` to execute with agents
+- Need requirements first? → `/write-a-prd` for structured product requirements
+- Want to stress-test the plan? → `/grill-me` for Socratic questioning
+- Ready to break into issues? → `/prd-to-plan` → `/triage-issue`

package/app/skills/refactor/SKILL.md

@@ -81,6 +81,16 @@ Before executing:
 - [ ] Tests passing
 - [ ] Backup created
 
+## Common Rationalizations
+
+| Excuse | Why It's Wrong |
+|--------|----------------|
+| "It works, don't touch it" | Working code that's hard to maintain slows every future change |
+| "We'll refactor it later" | Later never comes — refactor when the pain is fresh and context is loaded |
+| "It's too risky to change" | That's exactly why it needs refactoring — risk compounds with complexity |
+| "Just one more hack won't hurt" | Each hack makes the next one easier to justify — break the cycle now |
+| "We need to rewrite from scratch" | Incremental refactoring is safer and delivers value continuously |
+
 ## READ BEFORE WRITE
 
 This command analyzes and plans first.
@@ -122,3 +132,9 @@ Create an agent team for refactoring:
 - Teammate 2 (backend-specialist): "Implement the refactoring changes identified by the reviewer." Use Opus.
 Teammate 1 completes first, then Teammate 2 acts on the plan.
 ```
+
+## Related Skills
+- Need a safe refactor plan? → `/refactor-plan` for incremental steps as GitHub RFC
+- Want to validate architecture? → `/analyze` for code quality metrics
+- Need tests before refactoring? → `/tdd` to build safety net first
+- Architecture decision needed? → `/council` for multi-perspective evaluation