@rfxlamia/skillkit 1.0.0 → 1.2.0

package/skills/skills/framework-initiative/SKILL.md

@@ -0,0 +1,231 @@
+---
+name: framework-initiative
+description: Framework for agents to understand implicit user intent, think before acting, and consider action impact. Uses STAR framework (Stop-Think-Analyze-Respond) to prevent literal execution that doesn't match context. Use when agent receives ambiguous requests, abstract commands like "fix", "improve", "delete all", or actions with potential wide-scope impact. Trigger on code modification requests without explicit scope constraints.
+category: agent-frameworks
+---
+
+# Agent Initiative Framework
+
+## Overview
+
+Agent Initiative helps AI agents avoid **literal interpretation trap** - executing commands literally without understanding context and impact. This framework uses **STAR (Stop-Think-Analyze-Respond)** to ensure agents think before acting.
+
+**Metaphor:** When a user asks to "turn the world into paper because trees are gone," a good agent doesn't turn EVERYTHING into paper - but chooses what's appropriate (trash, inanimate objects) and protects living beings.
+
+## When to Use
+
+**Trigger conditions:**
+- User requests code changes without specifying explicit scope
+- Request involves abstract words ("fix", "improve", "change all")
+- Action potentially affects many files/components
+- No explicit constraints from user
+
+**Don't use when:**
+- User gives very specific instructions with clear scope
+- Task is read-only (analysis, explanation)
+- User explicitly asks to "execute immediately without analysis"
+
+---
+
+## Documentation vs Code Reality
+
+**Important Principle:** Documentation is a REFERENCE, not an OBLIGATION. Existing code is the primary source of truth.
+
+### Documentation Can Be Misleading
+
+In the AI era, documentation is often:
+- **Deprecated** - not updated even though code has changed
+- **Auto-generated** - created by tools without business context
+- **Template** - copy-pasted from other projects
+- **Outdated** - old versions that are no longer relevant
+
+### Trust Hierarchy
+
+```
+┌─────────────────────────────────────────┐
+│ SOURCE OF TRUTH HIERARCHY               │
+├─────────────────────────────────────────┤
+│ 1. Currently running code       ← Most  │
+│    (runtime behavior, actual logic)     │
+│                                         │
+│ 2. Passing test suite                   │
+│    (behavioral contracts)               │
+│                                         │
+│ 3. Git history & commit messages        │
+│    (intent and historical context)      │
+│                                         │
+│ 4. Code comments (if specific)          │
+│    (explanations of WHY, not WHAT)      │
+│                                         │
+│ 5. External documentation       ← Least │
+│    (README, wiki, API docs)     trusted │
+└─────────────────────────────────────────┘
+```
+
+### Execution Principles
+
+**Don't blindly trust documentation.** Verify with:
+
+1. **Read actual code** - What does this function actually do?
+2. **Trace execution path** - How does data flow?
+3. **Check test cases** - What behavior is expected?
+4. **Cross-reference** - Do docs match implementation?
+
+### Documentation Red Flags
+
+| Warning Sign | Action |
+|--------------|----------|
+| "According to documentation X but code doesn't work" | Prioritize code, documentation may be outdated |
+| "Documentation says A but test expects B" | Tests are contracts, documentation can be wrong |
+| "README says this feature exists but can't find it" | Check git history, may have been deleted |
+| "API docs don't match actual response" | Trust actual response, docs may not be updated |
+
+### Scenario Example
+
+**User:** "Add feature X according to this API documentation"
+
+**❌ Wrong:** Follow API documentation without verification → code error because endpoint has changed
+
+**✅ Correct:**
+1. Read documentation as INITIAL reference
+2. Check actual API calls in codebase
+3. Verify endpoint, payload, response structure
+4. Execute based on REALITY, not documentation
+
+---
+
+## STAR Framework
+
+### S - Stop (Pause Before Action)
+
+Before execution, **pause** and identify:
+
+```
+┌─────────────────────────────────────────┐
+│ STOP CHECKPOINT                         │
+├─────────────────────────────────────────┤
+│ 1. What did the user SAY?               │
+│ 2. What does the user MEAN?             │
+│ 3. Is there a gap between the two?      │
+└─────────────────────────────────────────┘
+```
+
+**Red flags that trigger STOP:**
+- "Fix this bug" (which bug? what's the scope?)
+- "Update all X to Y" (all = literally all?)
+- "Make it better" (criteria for "better"?)
+
+### T - Think (Identify Implicit Intent)
+
+Translate literal request into **actual intent**:
+
+| User Says | Might Actually Mean |
+|-----------|---------------------|
+| "Fix this function" | Fix function + update callers + update tests |
+| "Delete unused code" | Delete unused BUT preserve if might be needed |
+| "Rename X to Y everywhere" | Rename in code, but maybe not in API/DB |
+| "Make it faster" | Optimize hot paths, not micro-optimizations |
+
+**Questions to ask yourself:**
+1. What is the business/technical context of this request?
+2. What would the user be DISAPPOINTED by if I do it?
+3. What does the user ASSUME I know but didn't say?
+
+### A - Analyze (Map Impact & Dependencies)
+
+Before action, **scan** for dependencies:
+
+```bash
+# For code changes:
+1. Grep/Glob for usages of target
+2. Identify callers and dependencies
+3. Check test coverage
+4. Identify API contracts that might be affected
+```
+
+**Impact Zones:**
+
+```
+         ┌──────────────┐
+         │ Direct Zone  │ <- Direct target (file/function)
+         ├──────────────┤
+    ┌────┤ Caller Zone  │ <- Who calls this?
+    │    ├──────────────┤
+    │    │ Contract Zone│ <- API, interface, types
+    │    ├──────────────┤
+    └────┤ Test Zone    │ <- Tests that need updating
+         └──────────────┘
+```
+
+**For each zone, ask:**
+- Does change in Direct Zone affect other zones?
+- Are there breaking changes?
+- Are there silent failures that might occur?
+
+### R - Respond (Execute with Awareness)
+
+Execute with **graduated approach**:
+
+1. **Propose First**: Explain plan before execution
+2. **Scope Confirmation**: Confirm scope if ambiguous
+3. **Safe Order**: Execute from low-risk to high-risk
+4. **Verify After**: Check results match intent
+
+```
+┌─────────────────────────────────────────┐
+│ RESPONSE PATTERN                        │
+├─────────────────────────────────────────┤
+│ "I will [action] on [scope].            │
+│  This will affect [impact].             │
+│  I will NOT touch [exclude].            │
+│  Confirm before proceeding?"            │
+└─────────────────────────────────────────┘
+```
+
+---
+
+## Quick Reference
+
+### Intent Severity Levels
+
+| Level | Signal | Action |
+|-------|--------|--------|
+| **Low** | Specific, single-file, no deps | Direct execution |
+| **Medium** | Multi-file, has callers | STAR light (T+A) |
+| **High** | Abstract request, wide scope | Full STAR |
+
+### Pre-Action Checklist
+
+```
+□ Do I understand INTENT, not just WORDS?
+□ Have I scanned dependencies?
+□ Is there anything that might BREAK silently?
+□ Have I confirmed ambiguous scope?
+□ Can I ROLLBACK if wrong?
+```
+
+### Common Pitfalls
+
+| Pitfall | Example | Prevention |
+|---------|---------|------------|
+| Literal execution | "Delete X" → delete all X including important ones | Check importance before delete |
+| Scope creep | Fix bug A → refactor B, C, D | Stick to original scope |
+| Assumption blindness | Assume user wants X approach | Ask if ambiguous |
+| Silent breakage | Change function → caller breaks | Scan callers first |
+| Documentation trap | "Documentation says X" → follow without verification | Trust code reality, docs are just reference |
+
+---
+
+## Resources
+
+### references/
+- `star-framework.md` - Detailed STAR implementation
+- `impact-analysis.md` - Dependency analysis techniques
+- `intent-patterns.md` - Common implicit intent patterns
+- `examples.md` - Real-world examples
+
+---
+
+**Core Principles:**
+1. **Better to ask and confirm than to assume and break.**
+2. **Code reality > Documentation theory.** Documentation is reference, code is truth.

package/skills/skills/framework-initiative/references/examples.md

@@ -0,0 +1,150 @@
+# Real-World Examples
+
+## Example 1: The Code Repair Trap
+
+### Scenario
+User: "Fix this calculateTotal function"
+
+### Bad Agent Response (Literal)
+```javascript
+// Edit immediately without analysis
+function calculateTotal(items) {
+  return items.reduce((sum, item) => sum + item.price, 0);
+}
+// Bug fixed! (but turns out there are 12 callers expecting different formats)
+```
+
+### Good Agent Response (STAR Applied)
+
+**STOP:** "Fix" could mean many things.
+
+**THINK:** What's actually broken? Is there context I don't know?
+
+**ANALYZE:**
+```bash
+# Find all callers
+grep -r "calculateTotal" --include="*.js"
+# Result: 12 files call this function
+# 3 expect number, 5 expect object { total, tax }, 4 expect formatted string
+```
+
+**RESPOND:**
+"I found `calculateTotal` is called by 12 files with 3 different formats:
+- 3 files expect number
+- 5 files expect { total, tax }
+- 4 files expect formatted string
+
+Which specific bug did you mean? Or should I analyze each one?"
+
+---
+
+## Example 2: The Paper World Metaphor
+
+### Scenario
+User: "Turn the world into paper because trees are gone"
+
+### Bad Agent Response (Literal)
+```
+*Turning ALL entities into paper*
+- Humans → paper (DEAD)
+- Animals → paper (DEAD)
+- Buildings → paper (COLLAPSED)
+- Food → paper (STARVATION)
+```
+
+### Good Agent Response (STAR Applied)
+
+**STOP:** "World" is a metaphor. What's the actual scope?
+
+**THINK:**
+- Intent: solve paper shortage, not destroy everything
+- Constraints: living things should survive
+- Target: waste materials, non-essential items
+
+**ANALYZE:**
+- What can safely become paper? Trash, dead matter
+- What must NOT change? Living beings, food, shelter
+
+**RESPOND:**
+"I will turn the following into paper:
+- Plastic trash → paper (recycle)
+- Dry leaves → paper (natural)
+- Packaging waste → paper
+
+I will NOT change:
+- Living beings
+- Food
+- Important structures
+
+Is this what you intended?"
+
+---
+
+## Example 3: Delete Unused Code
+
+### Scenario
+User: "Delete all unused code"
+
+### Bad Agent Response (Literal)
+```bash
+# Delete everything with 0 direct references
+# Including: exported utilities, test helpers, future features
+```
+
+### Good Agent Response (STAR Applied)
+
+**STOP:** "Unused" needs definition.
+
+**THINK:**
+- Direct references = 0, but could be dynamic import
+- Exported = might be used externally
+- Test helpers = intentionally unused in production
+
+**ANALYZE:**
+```
+Found 15 "unused" items:
+- 5 internal helpers (no references) → SAFE
+- 4 exported functions → EXTERNAL RISK
+- 3 test utilities → INTENTIONAL
+- 3 feature flags (commented) → FUTURE USE
+```
+
+**RESPOND:**
+"Analysis of 'unused code':
+
+SAFE to delete (5 items):
+- `_legacyHelper()` - no refs, internal
+- `formatOldDate()` - replaced by new formatter
+- [3 more]
+
+NEED confirmation (4 items):
+- `publicApi.utils` - exported, might have external use
+- [3 more]
+
+DON'T delete (6 items):
+- Test utilities (intentional)
+- Feature flags (future use)
+
+Proceed with only the SAFE ones?"
+
+---
+
+## Pattern Summary
+
+| Scenario | Literal Trap | STAR Solution |
+|----------|-------------|---------------|
+| "Fix X" | Fix blindly | Analyze callers first |
+| "Delete unused" | Delete all zero-ref | Categorize by safety |
+| "Update all" | Update literally all | Identify actual scope |
+| "Make better" | Random improvements | Ask for specific criteria |
+| "Clean up" | Rewrite everything | Preserve existing behavior |
+
+---
+
+## Key Takeaway
+
+**The tree-paper metaphor shows:**
+- Literal requests can be absurd if executed literally
+- A good agent understands *intent* behind words
+- There's always implicit constraints not mentioned
+- Better to ask than to destroy

package/skills/skills/framework-initiative/references/impact-analysis.md

@@ -0,0 +1,157 @@
+# Impact Analysis Techniques
+
+## Dependency Graph Construction
+
+### Code-Level Dependencies
+
+**Function Dependencies:**
+```
+Target Function
+     │
+     ├── Callers (who calls this?)
+     │     ├── Direct callers
+     │     └── Indirect callers (caller's callers)
+     │
+     ├── Callees (what does this call?)
+     │     └── External dependencies
+     │
+     └── Shared State
+           ├── Global variables
+           ├── Module state
+           └── External resources (DB, files)
+```
+
+**File Dependencies:**
+```
+Target File
+     │
+     ├── Importers (who imports this?)
+     ├── Imports (what does this import?)
+     ├── Re-exports (pass-through dependencies)
+     └── Implicit (same directory, naming conventions)
+```
+
+### Type-Level Dependencies
+
+TypeScript/typed languages have an extra layer:
+- Interface implementations
+- Type aliases
+- Generic constraints
+- Union/intersection types
+
+---
+
+## Analysis Workflows
+
+### Workflow 1: Function Change
+
+```
+1. Find all callers
+   grep -r "functionName(" --include="*.ts"
+
+2. Check each caller's expectations
+   - Parameter types
+   - Return value usage
+   - Error handling
+
+3. Find tests
+   grep -r "functionName" --include="*.test.*"
+
+4. Check types/interfaces
+   grep -r "type.*functionName\|: functionName"
+```
+
+### Workflow 2: File Rename/Delete
+
+```
+1. Find all imports
+   grep -r "from.*oldFileName\|import.*oldFileName"
+
+2. Check for path references
+   grep -r "oldFileName" (in configs, tests, etc.)
+
+3. Check for dynamic imports
+   grep -r "import(" | grep "oldFileName"
+
+4. Check package.json exports (if applicable)
+```
+
+### Workflow 3: Type Change
+
+```
+1. Find all usages of the type
+   grep -r "TypeName" --include="*.ts"
+
+2. Check implements/extends
+   grep -r "implements.*TypeName\|extends.*TypeName"
+
+3. Check type assertions
+   grep -r "as TypeName\|<TypeName>"
+```
+
+---
+
+## Risk Assessment Matrix
+
+| Change Type | Scope | Risk Level | Action |
+|-------------|-------|------------|--------|
+| Local variable | Function | LOW | Proceed |
+| Function signature | Multiple callers | MEDIUM | Confirm scope |
+| Interface/Type | Unknown usages | HIGH | Full analysis |
+| Export rename | Unknown importers | HIGH | Full analysis |
+| Delete file | Unknown dependencies | CRITICAL | Deep analysis |
+
+---
+
+## Silent Failure Patterns
+
+### Pattern 1: Optional Chaining Hide Errors
+
+```typescript
+// Before: crashes if user is undefined
+const name = user.name;
+
+// After: silently returns undefined
+const name = user?.name;
+
+// Risk: undefined propagates silently
+```
+
+### Pattern 2: Default Parameter Masks
+
+```typescript
+// Before
+function fetch(url, options) { ... }
+
+// After (breaking for callers expecting positional)
+function fetch(url, options = {}) { ... }
+```
+
+### Pattern 3: Type Coercion
+
+```typescript
+// Loose equality hides type mismatch
+if (value == "5")  // true for value = 5
+
+// Strict would catch it
+if (value === "5") // false for value = 5
+```
+
+---
+
+## Tools for Impact Analysis
+
+### Built-in Searches
+- `grep -r`: Text search across files
+- `find`: Locate files by pattern
+- `git log -p`: History of changes
+
+### IDE Features
+- "Find All References"
+- "Go to Definition"
+- "Call Hierarchy"
+
+### Static Analysis
+- TypeScript compiler: `tsc --noEmit`
+- ESLint with appropriate plugins
+- Dependency cruiser: visualize dependencies

package/skills/skills/framework-initiative/references/intent-patterns.md

@@ -0,0 +1,145 @@
+# Common Implicit Intent Patterns
+
+## Pattern Categories
+
+### Category 1: Scope Expansion
+
+User says something specific, but implicitly expects broader handling.
+
+| Surface | Implicit Expansion |
+|---------|-------------------|
+| "Fix this bug" | Fix + prevent regression (add test) |
+| "Add this feature" | Add + integrate with existing |
+| "Update this API" | Update + update clients + update docs |
+
+**Detection:** Keywords "this", "the" without explicit scope.
+
+### Category 2: Scope Restriction
+
+User says something broad, but implicitly expects targeted action.
+
+| Surface | Implicit Restriction |
+|---------|---------------------|
+| "Delete unused code" | Delete unused BUT keep possibly-needed |
+| "Refactor everything" | Refactor BUT preserve behavior |
+| "Update all tests" | Update relevant tests, not literally all |
+
+**Detection:** Keywords "all", "every", "everything" in destructive context.
+
+### Category 3: Quality Assumptions
+
+User assumes certain quality standards without stating.
+
+| Unstated Assumption | What It Means |
+|--------------------|---------------|
+| Code should work | Include error handling |
+| Code should be maintainable | Follow existing patterns |
+| Changes should be safe | Don't break existing functionality |
+| Performance shouldn't degrade | Consider performance implications |
+
+**Detection:** Any code modification request.
+
+### Category 4: Domain Context
+
+User assumes domain knowledge is shared.
+
+| Domain | Common Implicit Knowledge |
+|--------|--------------------------|
+| API | Don't change public contracts without versioning |
+| Database | Don't drop tables without backup consideration |
+| Auth | Security implications are paramount |
+| Payment | Extra caution for financial operations |
+
+**Detection:** Keywords related to sensitive domains.
+
+---
+
+## Detection Heuristics
+
+### High-Confidence Implicit Intent
+
+**Pattern: Singular Reference to Plural Scope**
+```
+"Update the config" → probably all related configs
+"Fix the test" → probably all failing tests
+"Change the variable name" → probably all usages
+```
+
+**Pattern: Action Without Object Specification**
+```
+"Make it work" → fix the immediate issue
+"Clean this up" → improve readability, not restructure
+"Simplify" → reduce complexity, keep functionality
+```
+
+### Low-Confidence (Ask for Clarification)
+
+**Pattern: Contradictory Signals**
+```
+"Delete everything but keep it working"
+"Refactor completely but don't change behavior"
+"Update all files quickly"
+```
+
+**Pattern: Vague Quality Targets**
+```
+"Make it better" → better how?
+"Optimize this" → for what metric?
+"Improve performance" → latency? throughput? memory?
+```
+
+---
+
+## Intent Translation Examples
+
+### Example 1: Bug Fix Request
+
+**User says:** "Fix the login bug"
+
+**Think phase:**
+- Which login bug? (may be multiple)
+- Just the symptom or root cause?
+- Should I add tests?
+- Are there related auth issues?
+
+**Good response:**
+"I found 2 issues in the login flow:
+1. Null check missing at line 45
+2. Race condition in session handling
+
+Should I fix both or focus on one?"
+
+### Example 2: Feature Addition
+
+**User says:** "Add dark mode"
+
+**Think phase:**
+- Where should toggle be?
+- Persist preference?
+- Affect all components or specific?
+- What about existing color variables?
+
+**Good response:**
+"For dark mode, I will:
+1. Add CSS variables for theming
+2. Add toggle in settings
+3. Persist to localStorage
+
+Won't change existing color values without confirmation. OK?"
+
+### Example 3: Code Deletion
+
+**User says:** "Delete unused functions"
+
+**Think phase:**
+- Unused = no direct calls, or no reachable calls?
+- Include dynamically called functions?
+- What about exported but unused?
+- What about test helpers?
+
+**Good response:**
+"I found 5 functions without direct callers:
+- 3 internal helpers (safe to delete)
+- 2 exported functions (might be used externally)
+
+I will delete 3 internal helpers. 2 exported functions need confirmation."