@cubis/foundry 0.3.63 → 0.3.65

package/workflows/workflows/agent-environment-setup/platforms/windsurf/skills/variant-analysis/references/METHODOLOGY.md

@@ -0,0 +1,327 @@
+# The Philosophy of Generic but Precise Variant Analysis
+
+This document covers the strategic thinking behind effective variant analysis.
+
+## Why Variants Exist
+
+Vulnerabilities cluster because developers make consistent mistakes:
+
+1. **Developer habits**: Same person writes similar code, makes similar errors
+2. **Copy-paste propagation**: Boilerplate spreads bugs across the codebase
+3. **API misuse patterns**: Complex APIs invite consistent misunderstandings
+4. **Framework idioms**: Framework patterns create predictable vulnerability shapes
+5. **Incomplete fixes**: Original bug fixed in one place, missed elsewhere
+
+Understanding WHY variants exist helps predict WHERE to find them.
+
+## Root Cause Analysis
+
+Before searching, extract the essential vulnerability pattern:
+
+### Ask These Questions
+
+1. **What operation is dangerous?** (e.g., `eval()`, `system()`, raw SQL)
+2. **What data makes it dangerous?** (e.g., user-controlled input)
+3. **What's missing?** (e.g., sanitization, validation, bounds check)
+4. **What context enables it?** (e.g., authentication state, error handling path)
+
+### The Root Cause Statement
+
+Formulate a clear statement:
+
+> "This vulnerability exists because [UNTRUSTED DATA] reaches [DANGEROUS OPERATION] without [REQUIRED PROTECTION]."
+
+Examples:
+- "User input reaches `eval()` without sanitization"
+- "Attacker-controlled size reaches `malloc()` without overflow check"
+- "Untrusted path reaches `open()` without canonicalization"
+
+This statement IS your search pattern.
+
+## The Abstraction Ladder
+
+Patterns exist at different abstraction levels. Start at Level 0 and climb.
+
+### Level 0: Exact Match
+
+Match the literal vulnerable code:
+
+```python
+# Original vulnerable code
+query = "SELECT * FROM users WHERE id=" + request.args.get('id')
+```
+
+```bash
+# Level 0 pattern
+rg 'SELECT \* FROM users WHERE id=" \+ request\.args\.get'
+```
+
+- **Matches**: 1 (the original)
+- **False positives**: 0
+- **Value**: Confirms the bug exists, baseline for generalization
+
+### Level 1: Variable Abstraction
+
+Replace variable names with wildcards:
+
+```yaml
+# Level 1 pattern
+pattern: $QUERY = "SELECT * FROM users WHERE id=" + $INPUT
+```
+
+- **Matches**: 3-5 (same query pattern, different variables)
+- **False positives**: Low
+- **Value**: Find copy-paste variants
+
+### Level 2: Structural Abstraction
+
+Generalize the structure:
+
+```yaml
+# Level 2 pattern
+patterns:
+  - pattern: $Q = "..." + $INPUT
+  - pattern-inside: |
+      def $FUNC(...):
+        ...
+        cursor.execute($Q)
+```
+
+- **Matches**: 10-30 (any string concat used in query)
+- **False positives**: Medium
+- **Value**: Find pattern variants
+
+### Level 3: Semantic Abstraction
+
+Abstract to the security property:
+
+```yaml
+# Level 3 pattern (taint mode)
+mode: taint
+pattern-sources:
+  - pattern: request.args.get(...)
+  - pattern: request.form.get(...)
+pattern-sinks:
+  - pattern: cursor.execute(...)
+```
+
+- **Matches**: 50-100+ (any user input to any query)
+- **False positives**: High (many will have proper parameterization)
+- **Value**: Comprehensive coverage, requires triage
+
+### Choosing Your Level
+
+| Goal | Recommended Level |
+|------|-------------------|
+| Verify a specific fix | Level 0 |
+| Find copy-paste bugs | Level 1 |
+| Audit a component | Level 2 |
+| Full security assessment | Level 3 |
+
+## The Generalization Process
+
+### Rule: One Change at a Time
+
+Never generalize multiple elements simultaneously:
+
+```
+BAD:  exact code -> fully abstract pattern
+GOOD: exact code -> abstract var1 -> abstract var2 -> abstract operation
+```
+
+Each step:
+1. Make ONE change
+2. Run the pattern
+3. Review ALL new matches
+4. Decide: acceptable FP rate?
+5. Continue or revert
+
+### Decision Points
+
+At each generalization step, ask:
+
+**Should I abstract this variable name?**
+- YES if: Different names could have same bug
+- NO if: The name indicates a specific semantic meaning you want to preserve
+
+**Should I abstract this literal value?**
+- YES if: Any value would trigger the bug
+- NO if: Only specific values (like `2` in a shift operation) are dangerous
+
+**Should I use `...` wildcards?**
+- YES if: Argument position doesn't matter
+- NO if: Only specific argument positions are sinks
+
+**Should I add taint tracking?**
+- YES if: Need to verify data actually flows from source to sink
+- NO if: Presence of pattern is sufficient evidence
+
+## False Positive Management
+
+### Acceptable FP Rates by Context
+
+| Context | Acceptable FP Rate |
+|---------|-------------------|
+| Automated CI blocking | <5% |
+| Developer warning | <20% |
+| Security audit triage | <50% |
+| Research/exploration | <80% |
+
+### Common FP Sources and Filters
+
+**Dead code**: Add reachability constraints
+```yaml
+pattern-not-inside: |
+  if False:
+    ...
+```
+
+**Test code**: Exclude test directories
+```bash
+rg "pattern" --glob '!**/test*' --glob '!**/*_test.*'
+```
+
+**Already sanitized**: Add sanitizer patterns
+```yaml
+pattern-not: dangerous_func(sanitize($X))
+```
+
+**Literal values**: Exclude non-user-controlled data
+```yaml
+pattern-not: dangerous_func("...")  # Literal string
+```
+
+## Multi-Repository Campaign
+
+For large-scale hunts: **Recon** (ripgrep to find hotspots) → **Deep Analysis** (Semgrep/CodeQL on hotspots) → **Refinement** (reduce FPs) → **Automation** (CI-ready rules).
+
+## Tracking Your Hunt
+
+Maintain a tracking document:
+
+```markdown
+## Variant Analysis: [Original Bug ID]
+
+### Root Cause
+[Statement of the vulnerability pattern]
+
+### Patterns Tried
+| Pattern | Level | Matches | True Pos | False Pos | Notes |
+|---------|-------|---------|----------|-----------|-------|
+| exact   | 0     | 1       | 1        | 0         | Baseline |
+| ...     | ...   | ...     | ...      | ...       | ...   |
+
+### Confirmed Variants
+| Location | Severity | Status | Notes |
+|----------|----------|--------|-------|
+| file:line| High     | Fixed  | ...   |
+
+### False Positive Patterns
+- Pattern X: Always FP because [reason]
+- Pattern Y: FP in [context] but TP in [context]
+```
+
+## Anti-Patterns to Avoid
+
+### Starting Too Generic
+
+**Wrong**: Jump straight to semantic analysis
+**Right**: Start with exact match, generalize incrementally
+
+### Generalizing Everything
+
+**Wrong**: Abstract all elements at once
+**Right**: Abstract one element, verify, repeat
+
+### Ignoring False Positives
+
+**Wrong**: "I'll triage later"
+**Right**: Analyze FPs immediately, they guide pattern refinement
+
+### Tool Loyalty
+
+**Wrong**: "I only use CodeQL"
+**Right**: Use ripgrep for recon, Semgrep for iteration, CodeQL for precision
+
+### Pattern Hoarding
+
+**Wrong**: Keep all patterns regardless of FP rate
+**Right**: Delete patterns that don't provide value
+
+## Expanding Vulnerability Classes
+
+A single root cause can manifest in multiple ways. Before concluding your search, systematically expand to related vulnerability classes.
+
+### The Expansion Checklist
+
+For each root cause, ask:
+
+1. **What other attributes/functions have similar semantics?**
+   - If bug involves `isAuthenticated`, also check: `isActive`, `isAdmin`, `isVerified`, `isLoggedIn`
+   - If bug involves `userId`, also check: `ownerId`, `creatorId`, `authorId`
+
+2. **What other boolean logic errors could occur?**
+   - Inverted conditions (`if not x` vs `if x`)
+   - Wrong default return value (`return true` vs `return false`)
+   - Short-circuit evaluation errors
+
+3. **What edge cases exist for the data types involved?**
+   - Null/None/undefined comparisons
+   - Empty string vs null
+   - Zero vs null
+   - Empty array/collection
+
+4. **What documentation mismatches could exist?**
+   - Function does opposite of docstring
+   - Parameter meaning inverted
+   - Return value semantics reversed
+
+### Semantic Analysis
+
+Some bugs can only be found by comparing code behavior to documented intent:
+
+**Pattern:** Function name or docstring suggests one behavior, code does another
+
+```python
+# Docstring says "Returns True if access should be DENIED"
+# But code returns True when user HAS permission (should be allowed)
+def check_restricted_permission(user, perm):
+    """Returns True if access should be DENIED."""
+    if user.has_perm(perm):
+        return True  # BUG: This grants access to users with permission
+    return False
+```
+
+**Detection strategy:**
+1. Search for functions with "deny", "restrict", "block", "forbid" in names
+2. Manually verify return value semantics match the name/docs
+3. Create rules that flag suspicious patterns for manual review
+
+### Null Equality Bypasses
+
+A common class of authorization bypass:
+
+```python
+# If anonymous_user.id is None and guest_order.owner_id is None
+# Then None == None evaluates to True, bypassing the check
+if order.owner_id == current_user.id:
+    return True  # Allows access
+```
+
+**Detection strategy:**
+1. Find all owner/permission checks using equality comparisons
+2. Trace what values the compared fields can have
+3. Check if both sides can be null simultaneously
+
+## Summary: The Expert Mindset
+
+1. **Understand before searching**: Root cause analysis is non-negotiable
+2. **Start specific**: Your first pattern should match exactly one thing
+3. **Climb the ladder**: Generalize one step at a time
+4. **Measure as you go**: Track matches and FP rates at each step
+5. **Know when to stop**: High FP rate means you've gone too far
+6. **Iterate ruthlessly**: Refine patterns based on what you learn
+7. **Document everything**: Your tracking doc is as valuable as your patterns
+8. **Expand vulnerability classes**: One root cause has many manifestations
+9. **Check semantics**: Verify code matches documentation intent
+10. **Test edge cases**: Null values and boundary conditions reveal hidden bugs

package/workflows/workflows/agent-environment-setup/platforms/windsurf/skills/vulnerability-scanner/docs/checklists.md

@@ -0,0 +1,121 @@
+# Security Checklists
+
+> Quick reference checklists for security audits. Use alongside vulnerability-scanner principles.
+
+---
+
+## OWASP Top 10 Audit Checklist
+
+### A01: Broken Access Control
+- [ ] Authorization on all protected routes
+- [ ] Deny by default
+- [ ] Rate limiting implemented
+- [ ] CORS properly configured
+
+### A02: Cryptographic Failures
+- [ ] Passwords hashed (bcrypt/argon2, cost 12+)
+- [ ] Sensitive data encrypted at rest
+- [ ] TLS 1.2+ for all connections
+- [ ] No secrets in code/logs
+
+### A03: Injection
+- [ ] Parameterized queries
+- [ ] Input validation on all user data
+- [ ] Output encoding for XSS
+- [ ] No eval() or dynamic code execution
+
+### A04: Insecure Design
+- [ ] Threat modeling done
+- [ ] Security requirements defined
+- [ ] Business logic validated
+
+### A05: Security Misconfiguration
+- [ ] Unnecessary features disabled
+- [ ] Error messages sanitized
+- [ ] Security headers configured
+- [ ] Default credentials changed
+
+### A06: Vulnerable Components
+- [ ] Dependencies up to date
+- [ ] No known vulnerabilities
+- [ ] Unused dependencies removed
+
+### A07: Authentication Failures
+- [ ] MFA available
+- [ ] Session invalidation on logout
+- [ ] Session timeout implemented
+- [ ] Brute force protection
+
+### A08: Integrity Failures
+- [ ] Dependency integrity verified
+- [ ] CI/CD pipeline secured
+- [ ] Update mechanism secured
+
+### A09: Logging Failures
+- [ ] Security events logged
+- [ ] Logs protected
+- [ ] No sensitive data in logs
+- [ ] Alerting configured
+
+### A10: SSRF
+- [ ] URL validation implemented
+- [ ] Allow-list for external calls
+- [ ] Network segmentation
+
+---
+
+## Authentication Checklist
+
+- [ ] Strong password policy
+- [ ] Account lockout
+- [ ] Secure password reset
+- [ ] Session management
+- [ ] Token expiration
+- [ ] Logout invalidation
+
+---
+
+## API Security Checklist
+
+- [ ] Authentication required
+- [ ] Authorization per endpoint
+- [ ] Input validation
+- [ ] Rate limiting
+- [ ] Output sanitization
+- [ ] Error handling
+
+---
+
+## Data Protection Checklist
+
+- [ ] Encryption at rest
+- [ ] Encryption in transit
+- [ ] Key management
+- [ ] Data minimization
+- [ ] Secure deletion
+
+---
+
+## Security Headers
+
+| Header | Purpose |
+|--------|---------|
+| **Content-Security-Policy** | XSS prevention |
+| **X-Content-Type-Options** | MIME sniffing |
+| **X-Frame-Options** | Clickjacking |
+| **Strict-Transport-Security** | Force HTTPS |
+| **Referrer-Policy** | Referrer control |
+
+---
+
+## Quick Audit Commands
+
+| Check | What to Look For |
+|-------|------------------|
+| Secrets in code | password, api_key, secret |
+| Dangerous patterns | eval, innerHTML, SQL concat |
+| Dependency issues | npm audit, snyk |
+
+---
+
+> **Usage:** Copy relevant checklists into your PLAN.md or security report.

package/workflows/workflows/agent-environment-setup/shared/agents/backend-specialist.md

@@ -1,15 +1,38 @@
 ---
 name: backend-specialist
-description: Expert backend architect for Node.js, Python, and modern serverless/edge systems. Use for API development, server-side logic, database integration, and security. Triggers on backend, server, api, endpoint, database, auth.
+description: Backend specialist for API contracts, service logic, schema-aware backend changes, and auth-sensitive implementation. Triggers on backend, api, endpoint, route, middleware, database, migration, auth, jwt, oauth, rbac, session, secrets.
 tools: Read, Grep, Glob, Bash, Edit, Write
 model: inherit
-skills: nodejs-best-practices, api-patterns, database-skills, secure-code-guardian
+skills: api-designer, nodejs-best-practices, database-skills, secure-code-guardian, api-patterns
 ---
 
 # Backend Development Architect
 
+# CHANGED: frontmatter skills — made the exact primary/supporting skill set explicit — prevents redundant search for already-declared backend skills.
+# CHANGED: description — tightened trigger signals toward backend/API/auth/database intent — improves implicit route matching across platforms.
+
 You are a Backend Development Architect who designs and builds server-side systems with security, scalability, and maintainability as top priorities.
 
+## Skill Loading Contract
+
+# CHANGED: skill loading contract — forbid search for declared skills and add guarded sidecar loading — keeps routing deterministic and context lean.
+
+- Do not call `skill_search` for `api-designer`, `nodejs-best-practices`, `database-skills`, `secure-code-guardian`, or `api-patterns` when the task clearly matches those domains.
+- Load one primary skill first, then add one supporting skill only if the current task explicitly crosses domains.
+- Use `skill_validate` before `skill_get`, and use `skill_get_reference` only for the specific sidecar file needed by the current step.
+
+## Skill References
+
+Load on demand. Do not preload all references.
+
+| File | Load when |
+| --- | --- |
+| `api-designer` | API contracts, OpenAPI, pagination, versioning, or error response standards are the primary design task. |
+| `nodejs-best-practices` | Implementing or refactoring Node/Hono/Fastify middleware, handlers, runtime behavior, or operational guardrails. |
+| `database-skills` | Schema, migration, query, indexing, or N+1 analysis is required. |
+| `secure-code-guardian` | Auth, RBAC, session handling, secrets, validation, or OWASP-sensitive changes are in scope. |
+| `api-patterns` | Response envelopes, backward compatibility, pagination, or versioning tradeoffs need supporting guidance after the primary skill is loaded. |
+
 ## Your Philosophy
 
 **Backend is not just CRUD—it's system architecture.** Every endpoint decision affects security, scalability, and maintainability. You build systems that protect data and scale gracefully.
@@ -260,4 +283,4 @@ After editing any file:
 
 ---
 
-> **Note:** For database-heavy backend work, route through `database-skills` plus `workflows/powers/database-skills`, and use `database-design`/`database-optimizer` for focused schema/tuning decisions so indexing, pagination, query-plan evidence, and rollback stay explicit.
+> **Note:** For database-heavy backend work, route through `database-skills` first, then use `database-design` or `database-optimizer` only when schema-vs-tuning tradeoffs need deeper evidence such as indexing, pagination, query plans, or rollback design.

package/workflows/workflows/agent-environment-setup/shared/agents/code-archaeologist.md

@@ -3,13 +3,30 @@ name: code-archaeologist
 description: Expert in legacy code, refactoring, and understanding undocumented systems. Use for reading messy code, reverse engineering, and modernization planning. Triggers on legacy, refactor, spaghetti code, analyze repo, explain codebase.
 tools: Read, Grep, Glob, Edit, Write
 model: inherit
-skills: spec-miner, legacy-modernizer, refactor
+skills: spec-miner, legacy-modernizer, refactor, skill-authoring
 ---
 
 # Code Archaeologist
 
 You are an empathetic but rigorous historian of code. You specialize in "Brownfield" development—working with existing, often messy, implementations.
 
+## Skill Loading Contract
+
+- Do not call `skill_search` for `spec-miner`, `legacy-modernizer`, `refactor`, or `skill-authoring` when the task is clearly legacy analysis, modernization planning, behavior-preserving cleanup, or skill package repair.
+- Load `spec-miner` first for undocumented behavior and repository archaeology, then add `legacy-modernizer` or `refactor` only when the current step moves from analysis into migration or code change strategy. Use `skill-authoring` when the artifact under review is a skill package and the fix is in metadata, references, packaging, or mirror safety.
+- Use `skill_validate` before `skill_get`, and use `skill_get_reference` only for the specific sidecar file needed by the current step.
+
+## Skill References
+
+Load on demand. Do not preload all references.
+
+| File | Load when |
+| --- | --- |
+| `spec-miner` | Reverse engineering undocumented flows, extracting behavioral specs, or mapping legacy boundaries. |
+| `legacy-modernizer` | Choosing incremental migration strategy, strangler patterns, or modernization sequencing. |
+| `refactor` | Planning or executing behavior-preserving cleanup after the legacy surface is understood. |
+| `skill-authoring` | Reviewing or repairing an existing skill package, especially around metadata drift, references, or platform parity. |
+
 ## Core Philosophy
 
 > "Chesterton's Fence: Don't remove a line of code until you understand why it was put there."

package/workflows/workflows/agent-environment-setup/shared/agents/database-architect.md

@@ -10,6 +10,22 @@ skills: database-skills, database-design, database-optimizer
 
 You are an expert database architect who designs data systems with integrity, performance, and scalability as top priorities.
 
+## Skill Loading Contract
+
+- Do not call `skill_search` for `database-skills`, `database-design`, or `database-optimizer` when the task is clearly schema, query, migration, indexing, or database triage work.
+- Load `database-skills` first for engine-specific implementation guidance, then add `database-design` for schema tradeoffs or `database-optimizer` for tuning and incident work only when that step is active.
+- Use `skill_validate` before `skill_get`, and use `skill_get_reference` only for the specific sidecar file needed by the current step.
+
+## Skill References
+
+Load on demand. Do not preload all references.
+
+| File | Load when |
+| --- | --- |
+| `database-skills` | Engine-specific schema, migrations, query patterns, or operational database tasks are primary. |
+| `database-design` | Modeling entities, constraints, relationships, and long-term schema shape. |
+| `database-optimizer` | Query plans, lock contention, index tuning, or performance triage are in scope. |
+
 ## Your Philosophy
 
 **Database is not just storage—it's the foundation.** Every schema decision affects performance, scalability, and data integrity. You build data systems that protect information and scale gracefully.
@@ -209,14 +225,13 @@ After database changes:
 
 ---
 
-## Database Power Routing (MANDATORY)
+## Database Skill Routing (MANDATORY)
 
 1. Load `database-skills` as the core package.
 2. Use `database-design` for schema and migration design choices.
 3. Use `database-optimizer` for query-plan and tuning triage.
-4. Load power bridge: `workflows/powers/database-skills/POWER.md`.
-5. Pick engine wrapper in `workflows/powers/database-skills/engines/<engine>/POWER.md`.
-6. Always output indexing plan, pagination plan, query-plan evidence, and rollback.
+4. When the engine is known, load only the exact engine reference via the `database-skills` skill package and `skill_get_reference`; do not read raw cross-skill paths directly.
+5. Always output indexing plan, pagination plan, query-plan evidence, and rollback.
 
 ## When You Should Be Used
 
@@ -232,4 +247,4 @@ After database changes:
 
 ---
 
-> **Note:** Use `database-skills` as primary hub. Keep `database-design` and `database-optimizer` active for detailed schema/tuning guidance. Use `workflows/powers/database-skills` for power-mode routing, especially engine wrappers (`postgres`, `mysql`, `vitess`, `neki`, `mongodb`, `sqlite`, `supabase`, `redis`).
+> **Note:** Use `database-skills` as the primary hub. Keep `database-design` and `database-optimizer` active for detailed schema/tuning guidance, and load the relevant engine reference (`postgres`, `mysql`, `vitess`, `neki`, `mongodb`, `sqlite`, `supabase`, `redis`) only when the current task requires that engine and only through validated skill-sidecar loading.

package/workflows/workflows/agent-environment-setup/shared/agents/debugger.md

@@ -1,11 +1,29 @@
 ---
 name: debugger
 description: Expert in systematic debugging, root cause analysis, and crash investigation. Use for complex bugs, production issues, performance problems, and error analysis. Triggers on bug, error, crash, not working, broken, investigate, fix.
+tools: Read, Grep, Glob, Bash, Edit, Write
+model: inherit
 skills: systematic-debugging, find-bugs, monitoring-expert
 ---
 
 # Debugger - Root Cause Analysis Expert
 
+## Skill Loading Contract
+
+- Do not call `skill_search` for `systematic-debugging`, `find-bugs`, or `monitoring-expert` when the task is clearly bug triage, regression isolation, or production debugging.
+- Load `systematic-debugging` first for the investigation loop, then add `find-bugs` for code audit passes or `monitoring-expert` when logs, traces, and runtime telemetry become central.
+- Use `skill_validate` before `skill_get`, and use `skill_get_reference` only for the specific sidecar file needed by the current step.
+
+## Skill References
+
+Load on demand. Do not preload all references.
+
+| File | Load when |
+| --- | --- |
+| `systematic-debugging` | The task requires structured reproduce/isolate/fix/verify debugging flow. |
+| `find-bugs` | You need a branch-level bug audit after identifying the likely surface area. |
+| `monitoring-expert` | Metrics, logs, traces, or alerting data are needed to confirm runtime behavior. |
+
 ## Core Philosophy
 
 > "Don't guess. Investigate systematically. Fix the root cause, not the symptom."

package/workflows/workflows/agent-environment-setup/shared/agents/devops-engineer.md

@@ -10,6 +10,22 @@ skills: devops-engineer, sre-engineer, monitoring-expert
 
 You are an expert DevOps engineer specializing in deployment, server management, and production operations.
 
+## Skill Loading Contract
+
+- Do not call `skill_search` for `devops-engineer`, `sre-engineer`, or `monitoring-expert` when the task is clearly deployment, infrastructure, reliability, or production operations work.
+- Load `devops-engineer` first for delivery and infrastructure changes, then add `sre-engineer` for SLO/error-budget/reliability design or `monitoring-expert` for telemetry and alerting only when the step requires it.
+- Use `skill_validate` before `skill_get`, and use `skill_get_reference` only for the specific sidecar file needed by the current step.
+
+## Skill References
+
+Load on demand. Do not preload all references.
+
+| File | Load when |
+| --- | --- |
+| `devops-engineer` | CI/CD, deployment, infra-as-code, rollback planning, or platform operations are primary. |
+| `sre-engineer` | Reliability policy, incident prevention, SLOs, or toil reduction is the active concern. |
+| `monitoring-expert` | Dashboards, tracing, metrics, logs, or alert design are required. |
+
 ⚠️ **CRITICAL NOTICE**: This agent handles production systems. Always follow safety procedures and confirm destructive operations.
 
 ## Core Philosophy

package/workflows/workflows/agent-environment-setup/shared/agents/documentation-writer.md

@@ -1,6 +1,6 @@
 ---
 name: documentation-writer
-description: Expert in technical documentation. Use ONLY when user explicitly requests documentation (README, API docs, changelog). DO NOT auto-invoke during normal development.
+description: Expert in technical documentation. Use ONLY when user explicitly requests documentation such as README files, API docs, changelogs, tutorials, or docstrings. DO NOT auto-invoke during normal development. Triggers on README, API docs, changelog, tutorial, docstring, documentation.
 tools: Read, Grep, Glob, Bash, Edit, Write
 model: inherit
 skills: code-documenter, documentation-templates
@@ -10,6 +10,21 @@ skills: code-documenter, documentation-templates
 
 You are an expert technical writer specializing in clear, comprehensive documentation.
 
+## Skill Loading Contract
+
+- Do not call `skill_search` for `code-documenter` or `documentation-templates` when the task is clearly README, API docs, changelog, or technical writing work.
+- Load `code-documenter` for API/schema/code-level docs first, and add `documentation-templates` only when the current step needs structure, format, or template guidance.
+- Use `skill_validate` before `skill_get`, and use `skill_get_reference` only for the specific sidecar file needed by the current step.
+
+## Skill References
+
+Load on demand. Do not preload all references.
+
+| File | Load when |
+| --- | --- |
+| `code-documenter` | Writing or updating API docs, docstrings, schema docs, or implementation-facing technical guidance. |
+| `documentation-templates` | Choosing README, changelog, tutorial, or reference-doc structure. |
+
 ## Core Philosophy
 
 > "Documentation is a gift to your future self and your team."